<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>Aria: ARIA Developer&#39;s Reference Manual</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Aria
   &#160;<span id="projectnumber">2.9.4</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Class Categories</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">ARIA Developer's Reference Manual </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>MobileRobots <b>Advanced Robotics Interface for Applications (ARIA)</b></p>
<p>Copyright 2002, 2003, 2004, 2005 ActivMedia Robotics, LLC. All rights reserved.<br />
 Copyright 2006, 2007, 2008, 2009, 2010 MobileRobots Inc. All rights reserved.<br />
 Copyright 2011, 2012, 2013, 2014, 2015 Adept Technology. All rights reserved. Copyright 2016, 2017 Omron Adept MobileRobots. All rights reserved. </p>
<p> 
<style type="text/css">
  dt.file {
    font-family: monospace, typewriter, sans;
  }
  dl {
    font-size: small;
    margin-left: 10%;
    margin-right: 10%;
  }
</style>
</p>
<h1><a class="anchor" id="toc"></a>
Contents</h1>
<ul>
<li>
<a class="el" href="index.html#intro">Introduction</a> <ul>
<li>
<a class="el" href="index.html#javapython">Java and Python</a> </li>
<li>
<a class="el" href="index.html#matlab">Matlab</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#licensing">License and Sharing</a> </li>
<li>
<a class="el" href="index.html#AriaPackage">The ARIA Package</a> <ul>
<li>
<a class="el" href="index.html#arpack">ARIA/</a> </li>
<li>
<a class="el" href="index.html#arpackother">Other ARIA Files of Note</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#codingConventions">Documentation and Coding Convention</a> </li>
<li>
<a class="el" href="index.html#arCliServ">ARIA-Robot Client-Server Relationship</a> </li>
<li>
<a class="el" href="index.html#commClasses">Robot Communication</a> <ul>
<li>
<a class="el" href="index.html#connectRobot">Connecting with a Robot or the Simulator</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#HardwareConfiguration">Specifying Details about Robot and Device Connections</a> <ul>
<li>
<a class="el" href="index.html#RobotParameterFiles">Robot Parameter Files</a> </li>
<li>
<a class="el" href="index.html#RuntimeOptions">Program Runtime Options</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#robot">ArRobot</a> <ul>
<li>
<a class="el" href="index.html#commands">Client Commands and Server Information Packets</a> </li>
<li>
<a class="el" href="index.html#packetHandlers">Packet Handlers</a> </li>
<li>
<a class="el" href="index.html#CommandPackets">Command Packets</a> </li>
<li>
<a class="el" href="index.html#syncRobot">Robot Synchronization Cycle</a> </li>
<li>
<a class="el" href="index.html#stateReflection">State Reflection</a> </li>
<li>
<a class="el" href="index.html#callback">Robot Callbacks</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#ClientCommands">Controlling the robot with Commands and Actions</a> <ul>
<li>
<a class="el" href="index.html#robotDirectCommands">Direct Commands</a> </li>
<li>
<a class="el" href="index.html#robotMotionCommands">Motion Command Functions</a> </li>
<li>
<a class="el" href="index.html#actions">Actions</a> </li>
<li>
<a class="el" href="index.html#actionDesired">Action Desired</a> </li>
<li>
<a class="el" href="index.html#resolvers">The Action Resolver</a> </li>
<li>
<a class="el" href="index.html#predefinedActions">Predefined Actions</a> </li>
<li>
<a class="el" href="index.html#actionInteractions">Mixing Actions</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#rangeDevices">Range Devices</a> </li>
<li>
<a class="el" href="index.html#functors">Functors</a> </li>
<li>
<a class="el" href="index.html#userInput">Keyboard and Joystick Input</a> </li>
<li>
<a class="el" href="index.html#threading">Threading</a> <ul>
<li>
<a class="el" href="index.html#syncObject">Thread Syncronizing Objects</a> </li>
<li>
<a class="el" href="index.html#asynctasks">Asynchronous Task Class</a> </li>
</ul>
</li>
<li>
<a class="el" href="index.html#aria">Global Data</a> </li>
</ul>
<h2><a class="anchor" id="tocToolbox"></a>
Additional tools in the ARIA toolbox:</h2>
<ul>
<li>
<a class="el" href="index.html#devices">Device and Accessory Interface Classes</a> </li>
<li>
<a class="el" href="index.html#utility">Utility Classes</a> </li>
<li>
<a class="el" href="index.html#arconfig">ArConfig</a> </li>
<li>
<a class="el" href="index.html#sockets">Sockets</a> </li>
<li>
<a class="el" href="index.html#arinfogroup">Shared Info Groups</a> </li>
<li>
<a class="el" href="index.html#maps">Maps</a> </li>
<li>
<a class="el" href="index.html#ArNetworking">ArNetworking</a> </li>
<li>
<a class="el" href="index.html#sound">Sound and Speech</a> </li>
</ul>
<h2><a class="anchor" id="tocDevHelp"></a>
Helpful information about C++ development with ARIA:</h2>
<ul>
<li>
<a class="el" href="index.html#emacs">Emacs</a> </li>
<li>
<a class="el" href="index.html#noneverydayC">Non-everyday use of C++</a> <ul>
<li>
<a class="el" href="index.html#stl">Standard Template Library</a> </li>
<li>
<a class="el" href="index.html#defaultArgs">Default Arguments</a> </li>
<li>
<a class="el" href="index.html#constructorChaining">Constructor Chaining</a> </li>
<li>
<a class="el" href="index.html#charsAndStrings">Chars and Strings, Win workaround</a> </li>
<li>
<a class="el" href="index.html#arexport">AREXPORT</a> </li>
<li>
<a class="el" href="index.html#exceptions">Exceptions</a> </li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="tocAdv"></a>
Advanced Usage:</h2>
<ul>
<li>
<a class="el" href="index.html#pieceMealUse">Piecemeal Use of ARIA</a> </li>
<li>
<a class="el" href="index.html#hardConnectRobot">Connecting with a Robot or the Simulator the hard way</a> <ul>
<li>
<a class="el" href="index.html#openDevice">Opening the Connection</a> </li>
<li>
<a class="el" href="index.html#devConnect">Robot Client-Server Connection</a> </li>
<li>
<a class="el" href="index.html#connrw">Connection Read, Write, Close and Timestamping</a> </li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>Welcome to ARIA, an object-oriented, robot control applications-programming interface for MobileRobots (and ActivMedia) intelligent mobile robots.</p>
<p>Written in the C++ language, ARIA is client-side software for easy, high-performance access to and management of the robot, as well as to the many accessory robot sensors and effectors. ARIA includes many useful utilities for general robot programming and cross-platform (Linux and Windows) programming as well.</p>
<p>You can access ARIA at different levels, from simply sending commands to the robot through <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> to development of higher-level intelligent behavior using <a class="el" href="index.html#actions">Actions</a>. (For a description of how to integrate parts of ARIA with your other code, see <a class="el" href="index.html#pieceMealUse">Piecemeal Use of ARIA</a>.)</p>
<p>An auxiliary library called ArNetworking is also included with ARIA. ArNetworking provides an easy to use, extensible framework for communication with remote programs over a network, such as MobileEyes.</p>
<p>This page contains an overview of ARIA. Read this overview to become familiar with the ARIA library and how to get started using it. Click a class or function link to view its details. A selection of the most important ARIA classes is listed in <a class="el" href="group__ImportantClasses.html">Important Classes</a> in the menu to the left, as well as <a class="el" href="group__OptionalClasses.html">Optional Classes</a>, <a class="el" href="group__DeviceClasses.html">Device Interface Classes</a>, <a class="el" href="group__UtilityClasses.html">Utility Classes</a> and <a class="el" href="group__ActionClasses.html">Predefined ArAction Classes</a>. All classes are available in the full class list and hierarchy links on the left.</p>
<p>New users should view this document along with the ARIA examples, README.txt, and your robot's operating manual as well.</p>
<p>You can download new versions of ARIA from <a href="http://robots.mobilerobots.com/ARIA">http://robots.mobilerobots.com/ARIA</a></p>
<h2><a class="anchor" id="whouses"></a>
What is ARIA? How does it relate to other MobileRobots software?</h2>
<p>ARIA is a programming library (SDK) for C++ programmers who want to access their MobileRobots or ActivMedia platform and accessories at either a high or low level. ARIA is also for those who have already prepared robot-control software and want to deploy it on one or more MobileRobots or ActivMedia mobile robot platforms. ARIA also provides various tools useful for robot programming in general.</p>
<p>In addition to providing a complete robot and accessory API to developers, ARIA also serves as a foundation for other libraries providing additional capabilities: For creating applications with built-in advanced navigation routines, you can use the additional ARNL or SONARNL libraries. To communicate with the MobileEyes graphical display/control program, or for general communication over the network, you can use ArNetworking. ArNetworking is included with ARIA in the ArNetworking directory. See the ArNetworking Reference Manual for more information.</p>
<p>Other libraries are available as well for specialized purposes, including speech synthesis and recognition, audio stream recording, playback and network transmission, video image capture, color tracking, etc. Browse the MobileRobots support web pages <a href="http://www.activrobots.com">http://www.activrobots.com</a> and <a href="http://robots.mobilerobots.com">http://robots.mobilerobots.com</a> for these libraries and other mobile robotics resources, including the MobileSim simulator which can be used used for programming and debugging before driving an actual robot.</p>
<p>Programmers working with ARIA should be familiar with using typical C++ concepts, including using classes and objects with simple inheritance, pointers, memory management, the STL containers, and the compiling and linking process. (See below for notes about accessing ARIA from Python or Java.) Experience with multiple threads is also helpful.</p>
<p>Read on for information about the key pieces of ARIA and how to get started. See the README.txt file for a brief practical overview of ARIA software development on Linux and Windows. Many example programs are available as well.</p>
<h2><a class="anchor" id="javapython"></a>
Java and Python</h2>
<p>ARIA, ArNetworking, ARNL and SONARNL now work in Java and Python! Each library has a Java wrapper and a Python wrapper. This means that you can write ARIA programs in Java or Python almost as if ARIA itself was written in these languages. This wrapper is automatically generated by <a href="http://www.swig.org">SWIG</a>, and the Python and Java APIs are almost the same as the C++ library. Exceptions will be noted in this reference manual.</p>
<p>Read javaExamples/README.txt file for directions on how to use the Java wrapper and pythonExamples/README.txt for directions on how to use the Python wrapper, and likewise see <a href="../ArNetworking/javaExamples" class="file">ArNetworking/javaExamples</a> and <a href="../ArNetworking/pythonExamples" class="file">ArNetworking/pythonExamples</a> for information about and examples of the ArNetworking Java and Python wrappers.</p>
<h2><a class="anchor" id="matlab"></a>
Matlab</h2>
<p>A subset of essential robot control and accessor functions from ARIA are now also available for use in Matlab. See matlab/README.txt for instructions on how to create and use this interface, and notes on what is available and what its requirements and supported platforms are.</p>
<h1><a class="anchor" id="licensing"></a>
License and Sharing</h1>
<p>ARIA is released under the GNU Public License, which means that the entire source code is included and may be copied. However, if you distribute any work which incorporates ARIA, you must also distribute the entire source code to that work, including ARIA with any modifications you may have made, under the same license terms. Read the included <a href="../LICENSE.txt">license text</a> for details. We open-sourced ARIA under the GPL not only for your convenience, but also so that you could share your enhancements to the software with the robotics community (you can share them via the aria-users mailing list). If you wish your enhancements to make it into the ARIA baseline, you will need to assign the copyright on those changes to MobileRobots, contact <a href="#" onclick="location.href='mai'+'lto:'+'ari'+'a-'+'sup'+'po'+'rt@'+'mo'+'bil'+'er'+'obo'+'ts'+'.co'+'m'; return false;">aria-<span style="display: none;">.nosp@m.</span>supp<span style="display: none;">.nosp@m.</span>ort@m<span style="display: none;">.nosp@m.</span>obil<span style="display: none;">.nosp@m.</span>erobo<span style="display: none;">.nosp@m.</span>ts.c<span style="display: none;">.nosp@m.</span>om</a> with these changes or with questions about this.</p>
<p>Accordingly, please do share your work, and please sign up for the exclusive <a href="#" onclick="location.href='mai'+'lto:'+'ARI'+'A-'+'use'+'rs'+'@mo'+'bi'+'ler'+'ob'+'ots'+'.c'+'om'; return false;">ARIA-<span style="display: none;">.nosp@m.</span>user<span style="display: none;">.nosp@m.</span>s@mob<span style="display: none;">.nosp@m.</span>iler<span style="display: none;">.nosp@m.</span>obots<span style="display: none;">.nosp@m.</span>.com</a> newslist so that you can benefit from others' work, too.</p>
<p>For answers to frequently asked questions about what the GPL allows and requires, see <a href="http://www.gnu.org/licenses/gpl-faq.html">http://www.gnu.org/licenses/gpl-faq.html</a> .</p>
<p>On the other hand, ARIA may be also licensed for proprietary, closed-source applications. Contact <a href="#" onclick="location.href='mai'+'lto:'+'sal'+'es'+'@mo'+'bi'+'ler'+'ob'+'ots'+'.c'+'om'; return false;">sales<span style="display: none;">.nosp@m.</span>@mob<span style="display: none;">.nosp@m.</span>ilero<span style="display: none;">.nosp@m.</span>bots<span style="display: none;">.nosp@m.</span>.com</a> for details.</p>
<h1><a class="anchor" id="AriaPackage"></a>
The ARIA Package</h1>
<h2><a class="anchor" id="arpack"></a>
ARIA/</h2>
<p> 
<dl>
  <dt class="file">README.txt</dt>
    <dd>Getting started; essential info. Includes tips on installing
        ARIA, rebuilding it, building example programs, and 
        using platform development tools. 
        Also see the README files in the examples/, advanced/, and tests/
        directories.</dd>

  <dt class="file">LICENSE.txt</dt>
    <dd>GPL license for redistributing ARIA or programs using ARIA</dd>

  <dt class="file">Changes.txt</dt>
    <dd>Summary of changes featured in each version of ARIA</dd>

  <dt class="file">INSTALL.txt</dt>
    <dd>Detailed instructions for installing ARIA on different platforms</dd>

  <dt class="file">docs/</dt>
    <dd>Library reference documentation (this manual).</dd>

  <dt class="file">examples/</dt>
    <dd>ARIA example programs -- a good place to start. Also see the Examples
        section of this reference manual; selected examples are also linked from
        classes and methods used by those examples.
    </dd>


  <dt class="file">include/</dt>
    <dd>Header files for ARIA</dd>

  <dt class="file">src/</dt>
    <dd>ARIA C++ source code files</dd>

  <dt class="file">params/</dt>
    <dd>Robot definition (parameter) files (p3dx.p, for example).
        Mostly used transparently by ARIA, but can be customized 
        if neccesary.
    </dd>

  <dt class="file">lib/</dt>
    <dd>Win32 DLL export library (.lib) files and Linux shared library (.so)
    files</dd>

  <dt class="file">bin/</dt>
    <dd>Win32 binaries and DLLs</dd>
</dl>
</p>
<h2><a class="anchor" id="arpackother"></a>
Other ARIA Files of Note</h2>
<p> 
<dl>
  <dt class="file">Makefile</dt>        <dd>Linux makefile for building ARIA and
  examples</dd>
  <dt class="file">Makefile.dep</dt>    <dd>Linux file dependency rules (used internally
  by Makefile)</dd>
  <dt class="file">utils/</dt>
    <dd>Utility programs, used internally by MobileRobots software development,
        plus some file format conversion tools
    </dd>
  <dt class="file">ArNetworking/</dt>   <dd>Networking infrastructure library,
  included with ARIA, but a separate library</dd>
  <dt class="file">tests/</dt>          <dd>Test files, somewhat esoteric but
  useful during ARIA development</dd>
  <dt class="file">advanced/</dt>       <dd>Advanced demos and examples, not
  always for the faint of heart (or ARIA novice)</dd>
  <dt class="file">pythonExamples/</dt> <dd>Information about and examples of
  using ARIA via Python</dd>
  <dt class="file">javaExamples/</dt>   <dd>Information about and examples of
  using ARIA via Java</dd>
  <dt class="file">python/</dt>         <dd>Contains ARIA Python module and
  other files</dd>
  <dt class="file">java/</dt>           <dd>Contains ARIA Java package and other
  files</dd>
</dl>
</p>
<h1><a class="anchor" id="codingConventions"></a>
Documentation and Coding Convention</h1>
<p>ARIA follows the following coding conventions:</p>
<ol>
<li>
Class names begin with "Ar" and are in mixed case. </li>
<li>
Enums and other constants either begin with a capital letter or are all in caps. </li>
<li>
Avoid preprocessor definitions whenever possible (instead using enumerations or inline methods) </li>
<li>
Member variables in classes are prefixed with 'my'. </li>
<li>
Static variables in classes are prefixed with 'our'. </li>
<li>
Member function names start with a lower case. </li>
<li>
Capitalize each word except the first one in a variable or method name; <code>likeThisForExample</code> </li>
<li>
All classes may be used in a multi-threaded program, either by being inherently threadsafe, or (more typically) by providing an API for protecting it by locking mutexes. See class documentation for notes on access from multiple threads.  </li>
</ol>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="index.html#emacs">Emacs</a></dd></dl>
<h1><a class="anchor" id="arCliServ"></a>
ARIA-Robot Client-Server Relationship</h1>
<p>For those of you who are familiar with SRI International's Saphira software and ActivMedia Robotics' mobile robots and their related technologies, the underlying client-server control architecture for the mobile platform, sensors, and accessories hasn't changed much in ARIA. It's just gotten a lot better and more accessible.</p>
<p>The core mobile robot "server" proceses are implemented in the Pioneer and AmigoBot Operating System firmware (ARCOS, AROS, P2OS, AmigOS, etc.), which runs on the robot's microcontroller. These proceses manage the more critical and time-sensitive low-level tasks of robot control and operation, including maintaining requested motion and heading state and estimating position from odometry, as well as acquiring sensor information (sonar and compass, for example) and driving many accessory components like the PTZ camera, TCM2 compass/inclinometer, and the Pioneer 5-DOF Arm. The robot, its microcontroller, firmware, and integrated devices (such as sonar) together are sometimes referred to as the "robot platform". The robot firmware does not, however, perform any high-level robotic tasks. Rather, it is the job of an intelligent client running on a connected PC to perform these application-level robotic control strategies and tasks, such as obstacle detection and avoidance, sensor fusion, localization, features recognition, mapping, intelligent navigation, PTZ camera control, Arm motion, and much more. ARIA's role is to support these client applications and their communcation with the robot firmware, to any devices that connect to the computer rather than the robot platform, and to remote software via a network.</p>
<p>The heart of ARIA is the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> class. This class manages the communication cycle with the firmware, receiving and providing access to data about the robot platform's operating state, triggering tasks within that cycle and determining commands to be sent back to the robot (see <a class="el" href="index.html#actions">Actions</a> and <a class="el" href="index.html#syncRobot">Robot Synchronization Cycle</a>). It also serves as a container for references to other ARIA objects (such as range devices) and a toolbox of general functions related to the mobile robot.</p>
<p>Through its <a class="el" href="index.html#actions">Actions</a> infrastructure, ARIA provides a powerful mechanism for combining independent behaviors to achieve coordinated motion control and intelligent guidance. With Actions, you easily implement the motion aspects of applications such as guided teleoperation, visual tracking, autonomous navigation, etc.</p>
<p>Other ARIA classes provide interfaces to access and control accessory sensors and devices, including operation and state reflection for sonar and laser range finders, pan-tilt units, arms, inertial navigation devices, and many others.</p>
<h1><a class="anchor" id="commClasses"></a>
Robot Communication</h1>
<p>One of the most important functions of ARIA, and one of the first and things that your application program must do, is to establish the connection between an <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> object instance and the robot platform operating system (firmware).</p>
<p>In addition to the mobile robot itself, some accessories, such as the sonar, the Pioneer Gripper, PTZ cameras, Pioneer Arm, compass, and others, are internally connected to the robot microcontroller's AUX or digital I/O lines, and use the robot connection as well (therefore the interface classes for these objects require a reference to an <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> object, which must be connected for the devices to work). Other accessories, such as the SICK laser, video capture cards, etc. are connected directly to the onboard computer.</p>
<p>There are several ways to connect a computer running ARIA to the robot's microcontroller or to a simulator. <a href="figures/Robot_Communication_Options.png">This figure</a> provides a schematic overview of the many ARIA-robot communication options. Consult your robot Operations Manual for more information about computer-robot hardware setup and communications.</p>
<h2><a class="anchor" id="connectRobot"></a>
Connecting with a Robot or the Simulator</h2>
<p>An <a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a> object is used to set up and perform the connection to the robot, based on robot parameter files, and run-time configuration via command-line arguments (see <a class="el" href="index.html#HardwareConfiguration">Specifying Details about Robot and Device Connections</a>). Similarly, <a class="el" href="classArLaserConnector.html" title="Create laser interface objects (for any kind of laser supported by ARIA) and connect to lasers based ...">ArLaserConnector</a> is used to connect to laser rangefinding devices. (Other connectors are also used for other kinds of accessory devices.) <a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a> and <a class="el" href="classArLaserConnector.html" title="Create laser interface objects (for any kind of laser supported by ARIA) and connect to lasers based ...">ArLaserConnector</a> are used in most of the example programs, including <a class="el" href="simpleConnect_8cpp-example.html">simpleConnect.cpp</a>, <a class="el" href="wander_8cpp-example.html">wander.cpp</a>, and <a class="el" href="demo_8cpp-example.html">demo.cpp</a>. (Some example still use the older <a class="el" href="classArSimpleConnector.html" title="Legacy connector for robot and laser. ">ArSimpleConnector</a>). <a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a> will first try to connect to a simulator on a local TCP port, and if no simulator is running, it will then connect to the robot on a local serial port. This makes it easy to develop and debug your program using the simulator, then simply copy it onto the robot's computer and run without modification. <a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a> also parses some command line arguments if supplied, which can explicitly specify a remote hostname and/or port to connect with via TCP, or to specify an alternate local serial port to use for robot connection, as well as other options. If a program uses <a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a>, running it with the "-help" command line argument will print a list of options.</p>
<p>Here is an example which uses <a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a> to connect the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> and <a class="el" href="classArLaserConnector.html" title="Create laser interface objects (for any kind of laser supported by ARIA) and connect to lasers based ...">ArLaserConnector</a> to connect to a laser rangefinder. </p><div class="fragment"><div class="line"><span class="preprocessor">#include &quot;Aria.h&quot;</span></div><div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)</div><div class="line">{</div><div class="line">  <a class="code" href="classAria.html#ad99c16b5d947229d9f8e1c5b2d4cdd73">Aria::init</a>();</div><div class="line">  <a class="code" href="classArArgumentParser.html">ArArgumentParser</a> parser(&amp;argc, argv);</div><div class="line">  parser.loadDefaultArguments();</div><div class="line">  <a class="code" href="classArRobot.html">ArRobot</a> robot;</div><div class="line">  <a class="code" href="classArRobotConnector.html">ArRobotConnector</a> robotConnector(&amp;parser, &amp;robot);</div><div class="line"></div><div class="line">  <span class="comment">// Try connecting to the robot.</span></div><div class="line">  <span class="keywordflow">if</span>(!robotConnector.connectRobot(&amp;robot))</div><div class="line">  {</div><div class="line">    <span class="comment">// Error!</span></div><div class="line">    <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a012daf6573594f91242f8dd7c02eb74b">ArLog::Terse</a>, <span class="stringliteral">&quot;Error, could not connect to robot.\n&quot;</span>);</div><div class="line">    robotConnector.logOptions();</div><div class="line">    <a class="code" href="classAria.html#a6abc3d39b3e9548063bb8e78375acc17">Aria::exit</a>(1);</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">// Run the ArRobot processing/task cycle thread.</span></div><div class="line">  robot.<a class="code" href="classArRobot.html#a3c3d878cfd11a2ef91230005a83bfcaa">runAsync</a>(<span class="keyword">true</span>);</div><div class="line"></div><div class="line">  <a class="code" href="classArLaserConnector.html">ArLaserConnector</a> laserConnector(&amp;parser, &amp;robot, &amp;robotConnector);</div><div class="line"></div><div class="line">  <span class="comment">// Parse command line arguments (there may be arguments specifying </span></div><div class="line">  <span class="comment">// what lasers to try to connect to)</span></div><div class="line">  <span class="keywordflow">if</span>(!<a class="code" href="classAria.html#a1b090c01d88bb420b8cf8e0384d25ee1">Aria::parseArgs</a>())</div><div class="line">  {</div><div class="line">    <a class="code" href="classAria.html#a10d71f3d4d0cf7f38c58a1f749f64a42">Aria::logOptions</a>();</div><div class="line">    <a class="code" href="classAria.html#a6abc3d39b3e9548063bb8e78375acc17">Aria::exit</a>(2);</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">// Try connecting to all lasers specified in the robot&#39;s parameter file</span></div><div class="line">  <span class="comment">// and in command line arguments</span></div><div class="line">  <span class="keywordflow">if</span>(!laserConnector.connectLasers())</div><div class="line">  {</div><div class="line">    <a class="code" href="classArLog.html#a43a8b3789126c818f390f24bdbceccce">ArLog::log</a>(<a class="code" href="classArLog.html#ac8cc0fb3aa323ab2a1c21340fdd1dce3a012daf6573594f91242f8dd7c02eb74b">ArLog::Terse</a>, <span class="stringliteral">&quot;Error, could not connect to lasers.\n&quot;</span>);</div><div class="line">    <a class="code" href="classAria.html#a10d71f3d4d0cf7f38c58a1f749f64a42">Aria::logOptions</a>();</div><div class="line">    <a class="code" href="classAria.html#a6abc3d39b3e9548063bb8e78375acc17">Aria::exit</a>(3);</div><div class="line">  }</div><div class="line"></div><div class="line">  <span class="comment">// Now we&#39;re connected, and the robot and laser objects are running in </span></div><div class="line">  <span class="comment">// background threads reading and processing data. (You can get access</span></div><div class="line">  <span class="comment">// to the ArLaser objects using ArRobot::findLaser() or</span></div><div class="line">  <span class="comment">// ArRobot::getLaserMap().</span></div><div class="line">  ...</div></div><!-- fragment --><h1><a class="anchor" id="HardwareConfiguration"></a>
Specifying Details about Robot and Device Connections</h1>
<p>On any individual robot, there are many possible combinations of hardware accessories, and several options for connecting accessories to the robot and computer. The device interface and connector classes (<a class="el" href="classArRobotConnector.html" title="Connect to robot or simulator based on program command line parameters. ">ArRobotConnector</a>, <a class="el" href="classArLaserConnector.html" title="Create laser interface objects (for any kind of laser supported by ARIA) and connect to lasers based ...">ArLaserConnector</a>, etc.) need information about what devices are connected and how they are connected, especially if they vary from their defaults.</p>
<p>This information is obtained from two sources: ARIA's parameter file(s) for the robot, and from program runtime arguments via <a class="el" href="classArArgumentParser.html" title="Parse and store program command-line arguments for use by other ARIA classes. ">ArArgumentParser</a> (which reads default program argument values from /etc/Aria.args (on Linux) and the ARIAARGS environment variable (on both Linux and Windows), then reads current program arguments from the command line).</p>
<p>Some examples of hardware configuration options that may need to be specified are what kinds of laser rangefinders are connected, and to which ports, laser connection and data parameters, what kind of GPS is connected and to what port (if a GPS is used). Furthermore, if you are connecting to a robot over a wireless TCP connection from an offboard computer rather than an onboard computer, you must provide a runtime command line argument giving the robot network name (and optionally port number).</p>
<h2><a class="anchor" id="RobotParameterFiles"></a>
Robot Parameter Files</h2>
<p>Robot parameter files are read by ARIA after a connection to the robot is made and the robot type and individual name are obtained (see <a class="el" href="index.html#connectRobot">Connecting with a Robot or the Simulator</a>). These files provide ARIA with robot-specific conversion factors and physical charactaristics, as well as accessory device connection information.</p>
<p>See <a class="el" href="ParamFiles.html">Robot Parameter Files</a> for more information.</p>
<h2><a class="anchor" id="RuntimeOptions"></a>
Program Runtime Options</h2>
<p>Various classes in ARIA (notably the Connector classes) use program runtime options (a/k/a command-line arguments).</p>
<p>See <a class="el" href="CommandLineOptions.html">Command Line Option Summary</a> for a summary of all the options that various classes in ARIA accept.</p>
<p>Arguments are provided to other ARIA classes by an <a class="el" href="classArArgumentParser.html" title="Parse and store program command-line arguments for use by other ARIA classes. ">ArArgumentParser</a> object. All ARIA programs should create an <a class="el" href="classArArgumentParser.html" title="Parse and store program command-line arguments for use by other ARIA classes. ">ArArgumentParser</a>, call <a class="el" href="classArArgumentParser.html#a501694b62a7f8b0c3cadd84aeafe1b35" title="Adds args from default files and environmental variables. ">ArArgumentParser::loadDefaultArguments()</a> to load any arguments that appear in the <code>/etc/Aria.args</code> file or <code>ARIAARGS</code> environment variable, and provide that object to any class constructors that accept it. Once all such objects are created, you can call <a class="el" href="classAria.html#a10d71f3d4d0cf7f38c58a1f749f64a42" title="Logs all the options for the program (Calls all the callbacks added with addLogOptionsCB()) ...">Aria::logOptions()</a> to print out a summary of all relevant options (e.g. call <a class="el" href="classAria.html#a10d71f3d4d0cf7f38c58a1f749f64a42" title="Logs all the options for the program (Calls all the callbacks added with addLogOptionsCB()) ...">Aria::logOptions()</a>; and <a class="el" href="classAria.html#a6abc3d39b3e9548063bb8e78375acc17" title="Shutdown all Aria processes/threads, call exit callbacks, and exit the program. ">Aria::exit()</a> if <a class="el" href="classArArgumentParser.html#ac3889cbdfa862031c51bf80e06954914" title="Checks for the help strings and warns about unparsed arguments. ">ArArgumentParser::checkHelpAndWarnUnparsed()</a> returns <code>true</code>, because the user gave the <code>&ndash;help</code> option). Finally, call <a class="el" href="classAria.html#a1b090c01d88bb420b8cf8e0384d25ee1" title="Parses the arguments for the program (calls all the callbacks added with addParseArgsCB()) ...">Aria::parseArgs()</a> to cause each of them to check the <a class="el" href="classArArgumentParser.html" title="Parse and store program command-line arguments for use by other ARIA classes. ">ArArgumentParser</a> for their respective arguments.</p>
<h1><a class="anchor" id="robot"></a>
ArRobot</h1>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> is the heart of an ARIA program, acting as robot communications gateway, central manager of robot state, tool for synchronizing program-added tasks and callbacks, <a class="el" href="classArAction.html" title="Base class for actions. ">ArAction</a> objects, etc.</p>
<h2><a class="anchor" id="commands"></a>
Client Commands and Server Information Packets</h2>
<p>Client-server communications between ARIA and a mobile robot platform or simulator use packet-based protocols. (In this context, the <em>client</em> is the software using ARIA to operate a robot, and the <em>server</em> is the robot platform's firmware.) The details of the client-server protocol can be found in your robot's Operations or Technical Manual.</p>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> (using the <a class="el" href="classArDeviceConnection.html" title="Base class for device connections. ">ArDeviceConnection</a>, <a class="el" href="classArRobotPacketReceiver.html" title="Given a device connection it receives packets from the robot through it. ">ArRobotPacketReceiver</a>, <a class="el" href="classArRobotPacketSender.html" title="Given a device connection this sends commands through it to the robot. ">ArRobotPacketSender</a>, <a class="el" href="classArRobotPacket.html" title="Represents the packets sent to the robot as well as those received from it. ">ArRobotPacket</a>, and <a class="el" href="classArSerialConnection.html" title="Utility for connecting to and communicating with devices through a serial port. ">ArSerialConnection</a> classes) handles the details of constructing and sending a command packets to the robot as well as receiving and decoding the packets recieved from the robot server.</p>
<h2><a class="anchor" id="packetHandlers"></a>
Packet Handlers</h2>
<p>Server Information Packets (SIPs) are packets sent by the robot server containing information updates about the robot and its accessories. The <em>standard SIP</em> is sent by the robot to a connected client automatically every 100 milliseconds (this frequency may be configured in the firmware parameters). It contains the robot's current position and estimates, current translational and rotational speeds, sonar reading updates, battery voltage, analog and digital I/O states, and more. These data are stored and used by <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s State Reflection (see <a class="el" href="index.html#stateReflection">State Reflection</a> below) and are accessible via methods of the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> class. (Note, within the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> source code the standard SIP is also called a "motor" packet.)</p>
<p><em>Extended SIPs</em> use the same packet format as the standard SIP, but with a different packet "type" code. Examples of extended SIPs include I/O port data, data from the gripper, or special robot data like raw encoder data. To receive extended SIPs, the client program must request them. In ARIA, this is normally done by the device interface classes (see <a class="el" href="index.html#devices">Device and Accessory Interface Classes</a>) when they are initialized or when the robot connection is established. You may also attach your own custom packet handlers to <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> using <a class="el" href="classArRobot.html#a9710774cf8be7f146ca58f83dd076e3f" title="Adds a packet handler to the list of packet handlers. ">ArRobot::addPacketHandler()</a>. You can use this to do your own additional processing of extended SIP data, or if creating an alternate implementation of a device interface class.</p>
<h2><a class="anchor" id="CommandPackets"></a>
Command Packets</h2>
<p>To control the robot platform, a client program sends <em>command packets</em> through the robot connection. This can be done using ArRobot's <a class="el" href="index.html#robotMotionCommands">Motion Command Functions</a>, using <a class="el" href="index.html#actions">Actions</a>, or at the most basic level, <a class="el" href="index.html#robotDirectCommands">Direct Commands</a>. Each of these methods results in command packets sent to the robot. This means that if both Actions and motion commands are used, or if independent program modules are sending motion commands, they may conflict. See <a class="el" href="index.html#ClientCommands">Controlling the robot with Commands and Actions</a> below for more about sending motion commands.</p>
<h2><a class="anchor" id="syncRobot"></a>
Robot Synchronization Cycle</h2>
<p>The standard SIP is sent on a constant cycle, and reception of this SIP triggers a new iteration of <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s <em>synchronized task processing cycle</em>. This cycle consists of a series of tasks, including SIP packet handling, invocation of sensor interpretation tasks, action handling and resolution, state reflection, and invocation of user tasks, in that order. Since the task cycle is (normally) triggered by the reception of each SIP (unless the robot platform begins to fails to send SIPs or the task cycle is explicitly dissasociated from the robot connection &ndash; see below), each task will be invoked in a predictable order, have the most recent data to act upon, no task will miss an opportunity to use a SIP, and as long as the tasks do not take too much time to execute, each SIP is handled as soon as possible after the robot sends it.</p>
<div class="image">
<img src="ArRobot_Task_Cycle.png" alt="ArRobot_Task_Cycle.png"/>
<div class="caption">
Overview of the ArRobot task cycle</div></div>
<p>To begin the processing cycle, call <a class="el" href="group__easy.html#gaaade8cc11da585cbdcec45f6c8fbe4a6" title="Starts the instance to do processing in this thread. ">ArRobot::run()</a> to enter the cycle synchronously, or <a class="el" href="group__easy.html#gac4425ceba89af5001dec83246190273a" title="Starts the instance to do processing in its own new thread. ">ArRobot::runAsync()</a> to run the cycle in a new background thread. <a class="el" href="group__easy.html#gaff02cf7043c2e7239ec6b6e11ff6b146" title="Stops the robot from doing any more processing. ">ArRobot::stopRunning()</a> stops the processing cycle.</p>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> provides methods to add your own sensor-interpretation and generic user task callbacks. To add a task callback, create an <a class="el" href="classArFunctor.html" title="An object which allows storing a generalized reference to a method with an object instance to call la...">ArFunctor</a> function object (see <a class="el" href="index.html#functors">Functors</a>) and then add it using <a class="el" href="classArRobot.html#ab3ed1a09a96c009802ed64bbc6c75325" title="Adds a sensor interpretation task. ">ArRobot::addSensorInterpTask()</a> or <a class="el" href="classArRobot.html#a50070f4e19b91aaac20772d15d9ad805" title="Adds a user task to the list of synchronous taskes. ">ArRobot::addUserTask()</a>. These tasks can be removed using <a class="el" href="classArRobot.html#a6c649876cb5cf82285c3775d6d7b8e62" title="Removes a sensor interp tasks by name. ">ArRobot::remSensorInterpTask()</a> or <a class="el" href="classArRobot.html#aaae2ceb1c4b1b0ddcdac8599ee0c8d49" title="Removes a user task from the list of synchronous taskes by name. ">ArRobot::remUserTask()</a>.</p>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> locks it's mutex (see <a class="el" href="classArRobot.html#a5aecc7ac998c9a31b82fdb904efa8609" title="Lock the robot instance. ">ArRobot::lock()</a> and <a class="el" href="classArRobot.html#a403d9de010dc2b8d478cd0b14b2d9491" title="Unlock the robot instance. ">ArRobot::unlock()</a>) during each iteration of the task cycle, so your task callbacks must not lock this mutex&ndash;a deadlock will occur. (However, locks must still be used for safe access to any other thread or ArAsyncTask, such as lasers and other range devices, or ARNL's planning or localization tasks.) This mutex lock protects <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> data from modification by other threads (if they correctly use the lock during access), and interruption of the series of tasks. So if you access <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> from any other thread (including the main thread, if you used <a class="el" href="group__easy.html#gac4425ceba89af5001dec83246190273a" title="Starts the instance to do processing in its own new thread. ">ArRobot::runAsync()</a> to run the task cycle), you must use <a class="el" href="classArRobot.html#a5aecc7ac998c9a31b82fdb904efa8609" title="Lock the robot instance. ">ArRobot::lock()</a> and <a class="el" href="classArRobot.html#a403d9de010dc2b8d478cd0b14b2d9491" title="Unlock the robot instance. ">ArRobot::unlock()</a> to lock and unlock the robot before and after any method call or use of any data in <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>.</p>
<p>It is also possible to run the processing cycle without a connection to a robot, if desired. This alternative cycle is not triggered by receiving a packet, instead it has its own steady, "chained" cycle time (default is 100 milliseconds which you may examine and reset with <a class="el" href="classArRobot.html#a3a7ff3682cb5e77de50800b8da83d411" title="Gets the number of ms between cycles. ">ArRobot::getCycleTime()</a> and <a class="el" href="classArRobot.html#a12d6cad67f61fbbde10197e6915c66ba" title="Sets the number of ms between cycles. ">ArRobot::setCycleTime()</a>). You may also explicitly disassociate <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s processing cycle from incoming SIP processing at any time by calling <a class="el" href="classArRobot.html#a4ba60a8bd859d34d31ffdaa75e54a2f7" title="Sets whether to chain the robot cycle to when we get in SIP packets. ">ArRobot::setCycleChained()</a> ("Chained" means that it is the end of a previous cycle that triggers the next after suitable delay to meet the desired cycle frequency). However, in doing so, you may degrade performance, as the robot's cycle will only be run every <a class="el" href="classArRobot.html#a3a7ff3682cb5e77de50800b8da83d411" title="Gets the number of ms between cycles. ">ArRobot::getCycleTime()</a> milliseconds, and each time only the most recently read (oldest) SIP is used (even if the robot has sent more than one since the last cycle).</p>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s synchronization task list is ipmlemented as a tree, with five major branches. Though it is uncommon to do so, a client program may modify this tree or disable branch tasks of the tree. If a particular task is disabled, none of its children will be called. The root of the task tree can be obtained by calling <a class="el" href="classArRobot.html#ab787d4d11031cbc29c53c2df2a07e3bb" title="This gets the root of the syncronous task tree, only serious developers should use it...">ArRobot::getSyncTaskRoot()</a>, which returns an <a class="el" href="classArSyncTask.html" title="Class used internally to manage the tasks that are called every cycle. ">ArSyncTask</a> object.</p>
<dl class="section warning"><dt>Warning</dt><dd>A user task or sensor interpretation task must run quickly. If one or more user tasks or actions runs such that the task cycle takes too long (more that 100ms) then the performance and behavior of the robot and of ARIA-robot communications will be negatively affected. In particular, do not call any functions that could block or wait for an unknown amount of time (such as locking a mutex that could be locked for a long time by another thread) or do any long loops waiting for a condition. Long-running activity can be performed in a separate asynchronous thread (See <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a>) instead, and results can be shared with the user task via storage which is protected by a mutex only during immediate reading and writing of the storage variables.</dd></dl>
<h2><a class="anchor" id="stateReflection"></a>
State Reflection</h2>
<p>State reflection in the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> class is the way ARIA maintains a snapshot of the robot's operating conditions and values, such as estimated pose, current velocity, battery voltage, etc. as extracted from the latest standard SIP. <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> methods for examining these values include <a class="el" href="group__easy.html#ga25c215578baa598a8916947bdf6e1285" title="Get the current stored global position of the robot. ">ArRobot::getPose()</a>, <a class="el" href="group__easy.html#ga4c994926aaefc4c86380f1a74e508a76" title="Gets the global X position of the robot. ">ArRobot::getX()</a>, <a class="el" href="group__easy.html#ga9164db66102fdf9d422feefdadffca92" title="Gets the global Y position of the robot. ">ArRobot::getY()</a>, <a class="el" href="group__easy.html#gaefe932449c50da9ca0f8084cd9639583" title="Gets the global angular position (&quot;theta&quot;) of the robot. ">ArRobot::getTh()</a>, <a class="el" href="group__easy.html#gad75dbd9aede7b7f57c9a38902b8aa1ce" title="Gets the current translational velocity of the robot. ">ArRobot::getVel()</a>, <a class="el" href="group__easy.html#gac2abfcd681cccdc2cf091d2901f0ba5b" title="Gets the current rotational velocity of the robot. ">ArRobot::getRotVel()</a>, <a class="el" href="classArRobot.html#a8d1637a9f3d37e55768d2aa1c8c272d6" title="Gets the battery voltage of the robot (normalized to 12 volt system) ">ArRobot::getBatteryVoltage()</a>, <a class="el" href="classArRobot.html#af27becf5512ffae66a4343e915de1a5a" title="Returns true if the left motor is stalled. ">ArRobot::isLeftMotorStalled()</a>, <a class="el" href="classArRobot.html#a537d668bed5b30eff99489e112a2dff0" title="Returns true if the left motor is stalled. ">ArRobot::isRightMotorStalled()</a>, <a class="el" href="classArRobot.html#a3067b7048faeb8353627b89179ae80a0" title="Gets the compass heading from the robot. ">ArRobot::getCompass()</a>, <a class="el" href="classArRobot.html#a882994178beeca41efb2cfc359ec17fb" title="Gets which analog port is selected. ">ArRobot::getAnalogPortSelected()</a>, <a class="el" href="classArRobot.html#a4a9b7cb46e7f9a3205db04b292ebe09b" title="Gets the analog value. ">ArRobot::getAnalog()</a>, <a class="el" href="classArRobot.html#a4dc15a333b8d16e1846fc59640802542" title="Gets the byte representing digital input status. ">ArRobot::getDigIn()</a>, <a class="el" href="classArRobot.html#a86c049112a9a84ac2785a8fef5a15869" title="Gets the byte representing digital output status. ">ArRobot::getDigOut()</a>.</p>
<p>The standard SIP also contains sonar reading updates, which are reflected in <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> and examined with the methods: <a class="el" href="group__easy.html#gae417de0a49281c6fcaec4a5092b87382" title="Find the number of sonar sensors (that the robot has yet returned values for) ">ArRobot::getNumSonar()</a>, <a class="el" href="group__easy.html#gabde522dc0c3d3b0057f59ee66e016dda" title="Gets the range of the last sonar reading for the given sonar. ">ArRobot::getSonarRange()</a>, <a class="el" href="classArRobot.html#a7b781d5e421844b5e35c32bc89b7173c" title="Find out if the given sonar reading was newly refreshed by the last incoming SIP received. ">ArRobot::isSonarNew()</a>, <a class="el" href="group__easy.html#gaaecbf0186c6fee1ca750723358a8a6ca" title="Returns the sonar reading for the given sonar. ">ArRobot::getSonarReading()</a>, <a class="el" href="group__easy.html#ga5a1512a405e305ff4a7ebd47e22b9fbb" title="Returns the closest of the current sonar reading in the given range. ">ArRobot::getClosestSonarRange()</a>, <a class="el" href="group__easy.html#ga30d3f70890eee08e172b21aace11ad39" title="Returns the number of the sonar that has the closest current reading in the given range...">ArRobot::getClosestSonarNumber()</a>. The sonar interface class, <a class="el" href="classArSonarDevice.html" title="Keep track of recent sonar readings from a robot as an ArRangeDevice. ">ArSonarDevice</a>, also receives this information (see <a class="el" href="index.html#rangeDevices">Range Devices</a>).</p>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> also uses the state reflection task to send previously requested motion commands (see <a class="el" href="index.html#robotMotionCommands">Motion Command Functions</a>) to the robot, so the motion commands sent to the robot reflects those desired values set in <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s state reflection by actions or motion command methods, and also so that the watchdog on the robot does not time out and disable the robot (if no motion command is set, <a class="el" href="classArCommands.html#a9a31f904a95bbc31d8b33c6637100cc4a3305dc8abf8857ef79fa774c735e2338" title="none, keep alive command, so watchdog doesn&#39;t trigger ">ArCommands::PULSE</a> is sent each cycle). You can further tune state reflection's motion command sending rate if neccesary with <a class="el" href="classArRobot.html#a57038192476e8422a6c6b949c96c239a" title="Sets the number of milliseconds between state reflection refreshes if the state has not changed...">ArRobot::setStateReflectionRefreshTime()</a>.) If desired, you may turn the motion-control state reflector off in the <a class="el" href="classArRobot.html#ab92dd002af5898b61ca6213e0c59f54e" title="Constructor. ">ArRobot::ArRobot()</a> constructor (set the <em>doStateReflection</em> parameter to false). This will cause motion command functions to only be send the command once directly to the robot whenever they are called, rather than storing the command to send each cycle.</p>
<h2><a class="anchor" id="callback"></a>
Robot Callbacks</h2>
<p>There are a number of useful callbacks invoked by <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> on connection events. You can add and remove them with the functions <a class="el" href="classArRobot.html#aa2d179de23b698c94d5bfc72eccdc4f9" title="Adds a connect callback. ">ArRobot::addConnectCB()</a>, <a class="el" href="classArRobot.html#a95735eb89c9a878714b49e172db5d9e0" title="Removes a connect callback. ">ArRobot::remConnectCB()</a>, <a class="el" href="classArRobot.html#aba145e49558e845364ae2a90b9616f8b" title="Adds a callback for when a connection to the robot is failed. ">ArRobot::addFailedConnectCB()</a>, <a class="el" href="classArRobot.html#a8c2207d45e57cea02057c48d8b9fb31e" title="Removes a callback for when a connection to the robot is failed. ">ArRobot::remFailedConnectCB()</a>, <a class="el" href="classArRobot.html#ac59da033f2b999a14f708b2383cf2433" title="Adds a callback for when disconnect is called while connected. ">ArRobot::addDisconnectNormallyCB()</a>, <a class="el" href="classArRobot.html#a3403c5d8f2c8f6c4fa811e43719b9ad6" title="Removes a callback for when disconnect is called while connected. ">ArRobot::remDisconnectNormallyCB()</a>, <a class="el" href="classArRobot.html#a6c72afa22282c5ca961d2fa3ff03ad0c" title="Adds a callback for when disconnection happens because of an error. ">ArRobot::addDisconnectOnErrorCB()</a>, <a class="el" href="classArRobot.html#ab14a65f2138e17bfdd695d26f784769f" title="Removes a callback for when disconnection happens because of an error. ">ArRobot::remDisconnectOnErrorCB()</a>, <a class="el" href="classArRobot.html#ad59f7982d20c7fdf77c5713dcec6b691" title="Adds a callback for when the run loop exits for what ever reason. ">ArRobot::addRunExitCB()</a>, <a class="el" href="classArRobot.html#a8082165c556ba05e2fabffde04746836" title="Removes a callback for when the run loop exits for what ever reason. ">ArRobot::remRunExitCB()</a>. Read their individual documentation pages for details.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="robotConnectionCallbacks_8cpp-example.html">robotConnectionCallbacks.cpp</a></dd></dl>
<h1><a class="anchor" id="ClientCommands"></a>
Controlling the robot with Commands and Actions</h1>
<p>Your ARIA client can drive the robot and run its various accessories through <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s Direct Commands, Motion Commands, or through Actions.</p>
<dl class="section note"><dt>Note</dt><dd>The robot's movement speed will be limited by several parameters. First, the maximum velocities, accelerations and decelerations given in ARIA's robot parameter file (.p file) (TransVelMax, RotVelMax, TransAccel, TransDecel, RotAccel, RotDecel, and for the Seekur only, LatVelMax, LatAccel and LatDecel) are used to limit motion commands sent by ARIA, if the value is nonzero. Next, the max velocities given in the robot firmware (ARCOS) configuration are used to limit motion commands recieved by the robot. All of these maximum values can be changed at runtime with the <a class="el" href="classArRobot.html#ae0ba898c9723f384679d3ee5f8a3a168" title="Sets the maximum translational velocity. ">ArRobot::setTransVelMax()</a>, <a class="el" href="classArRobot.html#a1174e2ca727403081ef5bbbb13667fa8" title="Sets the maximum rotational velocity. ">ArRobot::setRotVelMax()</a>, and for the Seekur only, <a class="el" href="classArRobot.html#a1d0184490e5eef6ee6b18ead131e2ec2" title="Sets the maximum lateral velocity. ">ArRobot::setLatVelMax()</a> calls. These calls change the parameters in the robot firmware, as well as in ARIA. That is, they override any maximum values given in the robot parameter file (.p file). Finally, the "Top" parameters in the firmware (ARCOS) configuration limit speeds; these cannot be changed at runtime, only using the configuration program. Most robot parameter files use 0 values as maximums, disabling ARIA's initial limiting check; however, to make the Seekur easier to initially teleoperate at safe speeds, the velocity limits in seekur.p are set. Change these limits to 0 to remove those speed limits, and use the platform's defaults, or use <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s methods to change them at program runtime.</dd></dl>
<h2><a class="anchor" id="robotDirectCommands"></a>
Direct Commands</h2>
<p>At the lowest level of robot access, you may send any command packet directly to the robot or simulator platform through <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>. Direct commands consist of a 1-byte command number followed by none or more arguments, as defined by the robot's operating system (ARCOS, AROS, P2OS, AmigOS, etc.). For example, the command number 4, ENABLE, enables the robot's motors if accompanied by the argument 1, and disables the motors with the argument 0. Use <a class="el" href="classArRobot.html#a165e27bc81ed9f159820dfdf215d5500" title="Sends a command to the robot with no arguments. ">ArRobot::com()</a> for commands that have no argument, such as PULSE; <a class="el" href="classArRobot.html#aceef80a6274fb34aafcc422e4b1778c1" title="Sends a command to the robot with an int for argument. ">ArRobot::comInt()</a> for a 2-byte integer argument, signed or unsigned, such as the motors ENABLE command; <a class="el" href="classArRobot.html#a37991669749d064691406e575b00564d" title="Sends a command to the robot with two bytes for argument. ">ArRobot::com2Bytes()</a> for commands that accept two individual bytes as the argument, such as the VEL2 command; and <a class="el" href="classArRobot.html#af0b32b39e44d1175b9cffa3f010459a1" title="Sends a command to the robot with a length-prefixed string for argument. ">ArRobot::comStr()</a> or <a class="el" href="classArRobot.html#a4dbea0c407858d3f715027a6832b9698" title="Sends a command to the robot with a length-prefixed string for argument. ">ArRobot::comStrN()</a> for a null-terminated or fixed-length string argument, respectively, such as the sonar POLLING sequencing command.</p>
<p>The <a class="el" href="classArCommands.html" title="A class containing names for most robot microcontroller system commands. ">ArCommands</a> class contains an enum with all the direct commands; <a class="el" href="classArCommands.html#a9a31f904a95bbc31d8b33c6637100cc4aa8d799cced5def80525936119963aad4" title="int, enable (1) or disable (0) motors ">ArCommands::ENABLE</a>, for example. Not all Direct Commands are supported by every MobileRobots robot, but unrecognized (or malformed) commands are simply ignored.</p>
<p>Please consult your robot's technical manual for details, such as the Chapter 6 in the Pioneer 3 Operations Manual, for client command numbers and syntax.</p>
<p>For most commands, a method exists in <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> that either sends the command immediately, or stores it for the state reflection task to send. However, the direct command methods allow you to send any unusual or special commands directly to the robot platform or simulator, without any intervening processing.</p>
<h2><a class="anchor" id="robotMotionCommands"></a>
Motion Command Functions</h2>
<p>At a level just above <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s Direct Commands are the Motion Command Functions. These are explicit simple movement commands sent by <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s state reflection task. For example, <a class="el" href="group__easy.html#gac4c369f0f8d8a41f2b3f2290bdcbb03c" title="Sets the velocity. ">ArRobot::setVel()</a> to set the translational velocity, <a class="el" href="group__easy.html#ga613157de1936d0c34ed73e32787ae661" title="Sets the rotational velocity. ">ArRobot::setRotVel</a> to set rotational velocity, <a class="el" href="classArRobot.html#a887e87b779740ad024f65c6ef67394cc" title="Sets differential movement if implemented by robot. ">ArRobot::setVel2()</a> to or set each wheel speeds separately, <a class="el" href="group__easy.html#gafbbe47b4351cc9baf2559d188803ee72" title="Sets the heading. ">ArRobot::setHeading()</a> to set a global heading angle to turn to, <a class="el" href="group__easy.html#ga09016d00e1f3ac9a502344d9e2cd548e" title="Move the given distance forward/backwards. ">ArRobot::move()</a> to drive a given distance, or <a class="el" href="group__easy.html#gac354fe63f9e58b33343f38923f1588fd" title="Stops the robot. ">ArRobot::stop()</a> to stop all motion. <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> also provides methods for setting speed limits beyond the limits set in the firmware configuration. These motion functions work at part of with <a class="el" href="index.html#stateReflection">State Reflection</a>, and <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> may resend commands each cycle to try to achieve the desired state.</p>
<p>Be aware that a Direct or a Motion Command may conflict with controls from Actions or other upper-level processes and lead to unexpected consequences. Use <a class="el" href="classArRobot.html#a5b1b947ef2e28d171f023b1bbe5d02a9" title="Clears what direct motion commands have been given, so actions work. ">ArRobot::clearDirectMotion()</a> to cancel the overriding effect of a previously set Motion Command so that your Action is able to regain control the robot. Or limit the time a Motion Command prevents other motion actions with <a class="el" href="classArRobot.html#a6f7742ed0fa340fb1ff917e4239e81e8" title="Sets the length of time a direct motion command will take precedence over actions, in milliseconds. ">ArRobot::setDirectMotionPrecedenceTime()</a>. Otherwise, the Motion Command will prevent actions forever. Use <a class="el" href="classArRobot.html#ab8d78b33276fef00976343d5e1aab141" title="Gets the length of time a direct motion command will take precedence over actions, in milliseconds. ">ArRobot::getDirectMotionPrecedenceTime()</a> to see how long a Motion Command takes precedence once set.</p>
<h2><a class="anchor" id="actions"></a>
Actions</h2>
<p>While simple sequences motion commands can be easy to use, trying to achieve more sophisticated motion using only motion commands can quickly become difficult. To make it possible to define complex behaviors out of independent, reusable components, ARIA provides the higher-level <em>Actions</em> system. Actions are individual objects that independently provide motion requests which are evaluated and then combined each cycle to produce a final set of movement commands. This allows you to build complex behavior from simple building blocks for dynamic and continuous motion control.</p>
<p>Actions are defined by creating a subclass of the <a class="el" href="classArAction.html" title="Base class for actions. ">ArAction</a> the base class which overloads the <a class="el" href="classArAction.html#a900675ede8563489ccc2e7e0934670bb" title="Fires the action, returning what the action wants to do. ">ArAction::fire()</a> method. See the <code><a class="el" href="actionExample_8cpp-example.html">actionExample.cpp</a></code> example program. ARIA also includes some useful pre-made action classes (see <a class="el" href="group__ActionClasses.html">Predefined ArAction Classes</a> for a list). Include these in your programs, or use them as examples when creating your own custom <a class="el" href="classArAction.html" title="Base class for actions. ">ArAction</a> subclass.</p>
<p>Actions are attached to an <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> object with <a class="el" href="group__easy.html#ga9ab030786d423237d3e4aa06c0e9d8ce" title="Adds an action to the list with the given priority. ">ArRobot::addAction()</a>, along with a priority which determines its position in the action list. <a class="el" href="classArAction.html#a51b27da0403d43cd916cbf49ba7ddc23" title="Sets the robot this action is driving. ">ArAction::setRobot()</a> is called on an action object when it is added to a robot. You can override this in your action subclass. (For example, this would be useful to add a connection callback, if there were some calculations you wished to do upon connection to the robot.)</p>
<p>Actions are evaluated by <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s <em>action resolver</em> in descending order of priority (highest priority first, lowest priority last) in each task cycle just prior to <a class="el" href="index.html#stateReflection">State Reflection</a>. The action resolver invokes each action's fire() method, combining their desired motion commands (the <a class="el" href="classArActionDesired.html" title="Contains values returned by ArAction objects expressing desired motion commands to resolver...">ArActionDesired</a> objects they return) to a single <a class="el" href="classArActionDesired.html" title="Contains values returned by ArAction objects expressing desired motion commands to resolver...">ArActionDesired</a> object, which is then used in state reflection to send motion commands to the robot.</p>
<dl class="section note"><dt>Note</dt><dd>Sending simple motion commands (e.g. by using <a class="el" href="group__easy.html#gac4c369f0f8d8a41f2b3f2290bdcbb03c" title="Sets the velocity. ">ArRobot::setVel()</a>) while actions are also active can result in conflicts between your simple motion commands and the action resolver's commands. See the discussion of <a class="el" href="index.html#robotMotionCommands">Motion Command Functions</a> above.</dd></dl>
<p>As the resolver is invoking each action, by it passes the current desired motion combined from the previously invoked, higher priority actions, as the currentDesired argument to fire(). This can be useful information if needed. (For example, a stall-recovery action could be programmed not to exert its motion effects if it has been pre-empted by a stop action, so this stall-recovery action would check currentDesired to see if either the "strength" is "used up" or if there is a maximum velocity, and if so, reset its own state.) However, there is no need for an action to pay attention to the currentDesired if not necessary.</p>
<dl class="section warning"><dt>Warning</dt><dd>An action must run quickly. If one or more actions or robot user tasks runs such that the task cycle takes too long (more that 100ms) then the performance and behavior of the robot and of ARIA-robot communications will be negatively affected. In particular, do not call any functions that could block or wait for an unknown amount of time (such as locking a mutex that could be locked for a long time by another thread) or do any long loops waiting for a condition. Long-running activity can be performed in a separate asynchronous thread (See <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a>) instead, and results can be shared with the action via storage which is protected by a mutex only during immediate reading and writing of the storage variables.</dd></dl>
<h2><a class="anchor" id="actionDesired"></a>
Action Desired</h2>
<p><a class="el" href="classArActionDesired.html" title="Contains values returned by ArAction objects expressing desired motion commands to resolver...">ArActionDesired</a> objects are used to pass desired action channel values and strengths out of an <a class="el" href="classArAction.html#a900675ede8563489ccc2e7e0934670bb" title="Fires the action, returning what the action wants to do. ">ArAction::fire()</a> method back to the resolver. An <a class="el" href="classArActionDesired.html" title="Contains values returned by ArAction objects expressing desired motion commands to resolver...">ArActionDesired</a> object should always be reset (<a class="el" href="classArActionDesired.html#ade8f095f408b4ed5e638bb4a72ad070b" title="Resets the strengths to 0. ">ArActionDesired::reset()</a>) before it is reused.</p>
<p>There are six action channels: velocity (<a class="el" href="classArActionDesired.html#a4c21aa3360c1e549d3d73df017ec68c7" title="Sets the velocity (mm/sec) and strength. ">ArActionDesired::setVel</a>), heading (<a class="el" href="classArActionDesired.html#aa61902c9c5835a8757dd8f2c41978b19" title="Sets the delta heading (deg) and strength. ">ArActionDesired::setDeltaHeading</a> or <a class="el" href="classArActionDesired.html#a85f311a6d30abaae6f588bcfc039c5b3" title="Sets the absolute heading (deg) ">ArActionDesired::setHeading</a> for absolute heading), maximum forward translational velocity (<a class="el" href="classArActionDesired.html#a4e8ddd5f5aeef35bd297708c5832d528" title="Sets the maximum velocity (+mm/sec) and strength. ">ArActionDesired::setMaxVel</a>), maximum reverse translational velocity (<a class="el" href="classArActionDesired.html#a248cf3dfd1aa49b821c0f1ea7a23d1db" title="Sets the maximum velocity for going backwards (-mm/sec) and strength. ">ArActionDesired::setMaxNegVel</a>), and maximum rotational velocity (<a class="el" href="classArActionDesired.html#acb13a7b648d4c549dcf03a91a7e9bca6" title="Sets the maximum rotational velocity (deg/sec) and strength. ">ArActionDesired::setMaxRotVel</a>).</p>
<p>An action gives each channel a strength between 0.0, the lowest, and 1.0, the highest. Strengths are used by the resolver to compute the relative effect of the associated channel when combining multiple actions' desired movements.</p>
<p>The maximum velocity, maximum negative velocity, and maximum rotational velocity channels simply impose speed limits and thereby indirectly control the robot.</p>
<p>For more advanced usage, <a class="el" href="classArActionDesired.html" title="Contains values returned by ArAction objects expressing desired motion commands to resolver...">ArActionDesired</a> objects can be merged (<a class="el" href="classArActionDesired.html#a3d7d5e7a28582b1d7f64e7e95631374b" title="Merges the given ArActionDesired into this one (this one has precedence), internal. ">ArActionDesired::merge</a>) and averaged (<a class="el" href="classArActionDesired.html#abe6f6ebad5228a6570b9b60f8e8a0e46" title="Starts the process of avereraging together different desireds. ">ArActionDesired::startAverage</a>, <a class="el" href="classArActionDesired.html#a807d6f1c606a5107cdbfa86f4c9752f7" title="Adds another actionDesired into the mix to average. ">ArActionDesired::addAverage</a>, <a class="el" href="classArActionDesired.html#adb9c18300aadb55a24fccd27af7a1e6c" title="Ends the process of avereraging together different desireds. ">ArActionDesired::endAverage</a>).</p>
<h2><a class="anchor" id="resolvers"></a>
The Action Resolver</h2>
<p><a class="el" href="classArResolver.html" title="Resolves a list of actions and returns what to do. ">ArResolver</a> is the base action resolver class. <a class="el" href="classArPriorityResolver.html" title="(Default resolver), takes the action list and uses the priority to resolve ">ArPriorityResolver</a> is the default resolver used by <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>.</p>
<p>The resolver used by <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> may be changed by calling <a class="el" href="classArRobot.html#a4716f07478a58c5c6a5c94353dd955ff" title="Sets the resolver the robot is using. ">ArRobot::setResolver</a>, if you wish to create an alternative <a class="el" href="classArResolver.html" title="Resolves a list of actions and returns what to do. ">ArResolver</a> implementation. There may only be one resolver per <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> object. (Though a resolver could contain within it multiple resolvers of its own.) Note that although a robot has one particular resolver bound to it, a resolver instance is not tied to any robot.</p>
<p>The priority resolver works by iterating through the action list in descending priority (from greatest priority value to lowest), setting each robot movement channel (trans. velocity, heading, max. velocity, etc.) based on the contributing actions' desired values (as returned from their fire() methods) in proportion to their respective strengths as well as the actions' priorities, updating each movement channel until its strength becomes 1.0 or the action list is exhausted. Once a channel's accumulated strength reaches 1.0, no more changes may be made to that channel (this is how higher priority actions can prevent lower priority actions from changing a channel). Same-priority actions are averaged together if they both provide outputs for the same channel.</p>
<p>As an example, the following table illustrates at each step an action's desired value and strength for the <b>velocity</b> channel, and the resulting change to the resolver's final velocity channel value and strength decision, for four fictional actions (A, B, C and D):</p>
<table  border="1" cellspacing="0" style="td, th { font-size: 90%; }" summary="Example result for velocity channel from four enabled actions">
<tr>
<th>step # </th><th>action </th><th>priority </th><th>value of action's desired-velocity channel </th><th>strength of action's desired-velocity channel </th><th>current final velocity value </th><th>current final velocity strength </th></tr>
<tr>
<td>1 </td><td>A </td><td>4 </td><td>-400 </td><td>0.25 </td><td>-400 </td><td>0.25 </td></tr>
<tr>
<td>2 </td><td>B </td><td>3 </td><td>-100 </td><td>1.0 </td><td colspan="2" rowspan="2" valign="middle" align="center">Combined for use in step 4 </td></tr>
<tr>
<td>3 </td><td>C </td><td>3 </td><td>200 </td><td>0.50  </td></tr>
<tr>
<td>4 </td><td>B&amp;C </td><td>3 </td><td>0 </td><td>0.75 </td><td>-100 </td><td>1.0 </td></tr>
<tr>
<td>5 </td><td>D </td><td>1 </td><td>500 </td><td>0.50 </td><td>no change </td><td>no change </td></tr>
<tr>
<th colspan="3" align="left">final result</th><td></td><td></td><td>-100</td><td>1.0 </td></tr>
</table>
<p>Notice in the example that the same-priority actions B and C are averaged before being combined with the previously computed values from step 1. The resulting combination is: ( (B desired velocity: -100) X (B velocity strength: 1.0) + (C desired velocity: 200) X (C velocity strength: 0.5) ) / 2 =&gt; (-100 + 100) / 2 =&gt; 0 Therefore actions B and C end up cancelling each other out. Combining this result with the "currentDesired" values computed in step 1 gives (step 1 desired velocity: -400) X (step 1 velocity strength: 0.25) + (step 4 desired velocity: 0) X (step 4 velocity strength: 0.75) =&gt; -100.</p>
<p>In this example, it turns out that at step 5, action D has no effect since the strength for this channel has reached 1.0 at step 4, before that action was considered by the resolver.</p>
<p>The same method is used for all of the other channels.</p>
<h2><a class="anchor" id="predefinedActions"></a>
Predefined Actions</h2>
<p>ARIA includes several predefined action classes. See <a class="el" href="group__ActionClasses.html">Predefined ArAction Classes</a> for a list. Include these in your programs, or use them as examples when creating your own custom <a class="el" href="classArAction.html" title="Base class for actions. ">ArAction</a> subclass.</p>
<p><em>Movement</em> action classes have an "ArAction" prefix and set either or both the translational velocity (setVel) and heading (setDeltaHeading and setHeading) channels to effect motion. <em>Limiting</em> action classes are prefixed with "ArActionLimiter" and set one or more of the maximum translational and rotational velocity channels, to slow down or prevent motion, usually based on conditions such as nearby sensor readings.</p>
<p>See the <a class="el" href="classArAction.html" title="Base class for actions. ">ArAction</a> base class's list of subclasses.</p>
<h2><a class="anchor" id="actionInteractions"></a>
Mixing Actions</h2>
<p>Actions are most useful when mixed. The <a class="el" href="teleopActionsExample_8cpp-example.html">teleopActionsExample.cpp</a> example program is a good example of mixing limiting and movement actions. It creates several limiting actions, including Limiter, LimiterFar, and so on, and two movement actions, joydriveAct and keydriveAct. The limiting actions have higher priority than the movement ones, thereby preventing driving if it might be potentially unsafe due to obstacles detected by sensors.</p>
<p>This example also illustrates fundamental, yet very powerful features of ARIA actions and how they contribute to the overall behavior of the mobile robot. Because they are individuals, contributing discretely to the movements of the robot, actions are easily reusable. For example, a limiting action that prevents the robot from crashing into a wall when translating forward, can be used, as is, in another ARIA program and have the identical effect, except that instead of driving the robot with a joystick, the new program's lower-priority movement action might use color-tracking to have the robot follow a rolling ball. The ball-following action doesn't need to know anything about the finer arts of safe navigation&ndash;the higher-priority limiting actions take care of that.</p>
<p>Another ARIA example program, <a class="el" href="wander_8cpp-example.html">wander.cpp</a> demonstrates how different movement actions can be used and how they interact. The stall-recover action in wander (<a class="el" href="classArActionStallRecover.html" title="Action to recover from a stall. ">ArActionStallRecover</a>) influences the robot's movements only when the motors are stalled, disabling the lower priority actions by using up all translational and rotational strength until the robot has extracted from the stall. You should also examine ArActionStallRecover.cpp in the src/ directory to see how the action changes its motion control influences based on the stall state. Also note how <a class="el" href="classArActionAvoidFront.html" title="This action does obstacle avoidance, controlling both trans and rot. ">ArActionAvoidFront</a> and <a class="el" href="classArActionConstantVelocity.html" title="Action for going straight at a constant velocity. ">ArActionConstantVelocity</a> interact.</p>
<h2><a class="anchor" id="actionGroups"></a>
Action Groups</h2>
<p>Action groups allow you to easily enable (activate) or disable (de-activate) a set of actions at once. You must first create an <a class="el" href="classArActionGroup.html" title="Group a set of ArAction objects together. ">ArActionGroup</a> attached to an <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>. Then, when you add an <a class="el" href="classArAction.html" title="Base class for actions. ">ArAction</a> to the <a class="el" href="classArActionGroup.html" title="Group a set of ArAction objects together. ">ArActionGroup</a>, it is automatically added to the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>, as well as to the group.</p>
<p>Several predefined action groups are provided by ARIA.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="actionGroupExample_8cpp-example.html">actionGroupExample.cpp</a></dd></dl>
<h1><a class="anchor" id="rangeDevices"></a>
Range Devices</h1>
<p>Range devices (<a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a>) are abstractions of sensors which detect the presence of obstacles in the space around the robot, providing a series of spatial readings over time. ARIA's range device classes transform all readings into specific points in the same two-dimensional global coordinate system. (This is the same coordinate system as <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>'s pose).</p>
<p>Currently, the main <a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> implementations included with ARIA are: sonar (<a class="el" href="classArSonarDevice.html" title="Keep track of recent sonar readings from a robot as an ArRangeDevice. ">ArSonarDevice</a>), laser (<a class="el" href="classArLaser.html" title="ArRangeDevice interface specialized for laser rangefinder sensors; see ArRangeDevice for more data ac...">ArLaser</a> and subclasses), the robot bumpers (<a class="el" href="classArBumpers.html" title="A class that treats the robot&#39;s bumpers as a range device. ">ArBumpers</a>), and the "table-sensing" infrared sensors of a PeopleBot (<a class="el" href="classArIRs.html" title="A class that treats a robot&#39;s infrared sensors as a range device. ">ArIRs</a>). Camera and 3D range devices (MobileRanger devices) are supported by separate software. In addition, <a class="el" href="classArForbiddenRangeDevice.html" title="Class that takes forbidden lines and turns them into range readings. ">ArForbiddenRangeDevice</a> is a "virtual" range device that creates range readings that border "forbidden area" and "forbidden line" regions in an <a class="el" href="classArMap.html" title="A map of a two-dimensional space the robot can navigate within, and which can be updated via the Aria...">ArMap</a>, and ArRangeDeviceFilter processes the output another <a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> object in a few ways and provides the processed data through the <a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> interface. Its parameters can be modified on line through <a class="el" href="classArConfig.html" title="Stores configuration information which may be read to and from files or other sources. ">ArConfig</a>.</p>
<p><a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> holds two kinds of <a class="el" href="classArRangeBuffer.html" title="This class is a buffer that holds ranging information. ">ArRangeBuffer</a> objects to store readings: <em>current</em> and <em>cumulative</em>, though not all <a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> implementations supply data to the cumulative buffer. The current buffer contains the most recent set of readings; the cumulative buffer contains readings gathered over a longer period time, limited by the buffer's size (see <a class="el" href="classArRangeBuffer.html#a34015d54951d3de04931fd88f84d74ac" title="Sets the size of the buffer. ">ArRangeBuffer::setSize()</a>).</p>
<p>Some range devices also provide "raw" readings, which are the original values given by the device itself. Some range devices are also considered "Planar", which means that the readings may undergo some processing to remove duplicates etc., and which include raw readings. This includes the lasers.</p>
<p>Range devices are connected to a specific <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> instance, to obtain position and other information from the robot when readings are received and stored, and also to provide a way to find all range devices attached to the robot. Some range devices use the robot connection to communicate to their device (e.g. <a class="el" href="classArSonarDevice.html" title="Keep track of recent sonar readings from a robot as an ArRangeDevice. ">ArSonarDevice</a>, <a class="el" href="classArBumpers.html" title="A class that treats the robot&#39;s bumpers as a range device. ">ArBumpers</a>, <a class="el" href="classArIRs.html" title="A class that treats a robot&#39;s infrared sensors as a range device. ">ArIRs</a>). Attach an <a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> to your <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> object with <a class="el" href="classArRobot.html#a97d57b28549fdef851c00749a97cc776" title="Adds a rangeDevice to the robot&#39;s list of them, and set the ArRangeDevice object&#39;s robot pointer to t...">ArRobot::addRangeDevice()</a> and remove it with <a class="el" href="classArRobot.html#a23710c00dae49858a704dd1e066e21ed" title="Remove a range device from the robot&#39;s list, by name. ">ArRobot::remRangeDevice()</a>. The list of all attached devices can be queried using <a class="el" href="classArRobot.html#a1f42bf67e357145f7f60d7ff3f8226c7" title="Finds a rangeDevice in the robot&#39;s list. ">ArRobot::findRangeDevice()</a> and <a class="el" href="classArRobot.html#a52a4db2a7950766f109f588717e95559" title="Finds whether a particular range device is attached to this robot or not. ">ArRobot::hasRangeDevice()</a>. The list can be obtained by calling <a class="el" href="classArRobot.html#adb9735381c55527b552fce2e702adc39" title="Gets the range device list. ">ArRobot::getRangeDeviceList()</a>.</p>
<p>(Note that although sonar are integrated with the robot microcontroller, and the microcontroller always sends sonar data to the robot (if the robot has sonar), you still must attach an <a class="el" href="classArSonarDevice.html" title="Keep track of recent sonar readings from a robot as an ArRangeDevice. ">ArSonarDevice</a> object to the robot to use it.)</p>
<p><a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> also includes some methods to help find the closest reading to the robot within a selected box, or a polar sector: <a class="el" href="classArRangeDevice.html#a27b080d64bdedd8f593ffcc6c373d609" title="Gets the closest current reading in the given polar region. ">ArRangeDevice::currentReadingPolar()</a>, <a class="el" href="classArRangeDevice.html#ac262870eb43b21b1be17ee8621eb3b91" title="Gets the closest current reading from the given box region. ">ArRangeDevice::currentReadingBox()</a>, <a class="el" href="classArRangeDevice.html#a3c898926eb1c04ed457c8e5c3e7566e3" title="Gets the closest cumulative reading in the given polar region. ">ArRangeDevice::cumulativeReadingPolar()</a>, <a class="el" href="classArRangeDevice.html#adeab2edd7763ac30d2b33c1cf08bb915" title="Gets the closest current reading from the given box region. ">ArRangeDevice::cumulativeReadingBox()</a>.</p>
<p><a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> also includes similar methods to do common operations on all attached range devices, including <a class="el" href="classArRobot.html#af022d2fe8078cd7f9dc82631e40fad13" title="Goes through all the range devices and checks them. ">ArRobot::checkRangeDevicesCurrentPolar()</a>, <a class="el" href="classArRobot.html#af0c545d675b449171f5523513abea282" title="Gets the closest reading in a region defined by the two points of a rectangle. ">ArRobot::checkRangeDevicesCurrentBox()</a>, ArRobot::checkRangesDevicesCumulativePolar(), and <a class="el" href="classArRobot.html#a2e2de80c209361b5480f27a6c58fd482" title="Gets the closest reading in a region defined by the two points of a rectangle. ">ArRobot::checkRangeDevicesCumulativeBox()</a> to find the closest range reading to the robot within some region.</p>
<p>Each range device has a mutex (Use <a class="el" href="classArRangeDevice.html#a172e8da71d800f959523e1f3021612d8" title="Lock this device. ">ArRangeDevice::lockDevice()</a> and <a class="el" href="classArRangeDevice.html#af889a070950aae211df4637fbb73608e" title="Unlock this device. ">ArRangeDevice::unlockDevice()</a> to lock and unlock it) so that it can be accessed safely by multiple threads. For example, <a class="el" href="classArLMS2xx.html" title="Interface to a SICK LMS-200 laser range device. ">ArLMS2xx</a> uses a thread to read data from a laser, but the checkRangeDevice functions in <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> lockDevice() so they can read the data without conflicting with <a class="el" href="classArLMS2xx.html" title="Interface to a SICK LMS-200 laser range device. ">ArLMS2xx</a>'s data-reading thread, then use unlockDevice() when done. See <a class="el" href="index.html#threading">Threading</a> for more about threading in ARIA.</p>
<h1><a class="anchor" id="functors"></a>
Functors</h1>
<p>Functors are used throughout ARIA. Functor is short for function pointer. A Functor lets you call a function without knowing the declaration of the function. Instead, the compiler and linker figure out how to properly call the function.</p>
<p>Function pointers are fully supported by the C language. C++ treats function pointers like C, but to call class methods, an instance object is required, as well as type information about the class. Therefore, ARIA contains a set of template classes to contain this information.</p>
<p>ARIA makes heavy use of ArFunctors as "callback" functions. To instantiate a functor, you first need to identify how many arguments the function needs and if it returns a value. Many times a pointer to the abstract <a class="el" href="classArFunctor.html" title="An object which allows storing a generalized reference to a method with an object instance to call la...">ArFunctor</a> base class is used, which can be invoked with no arguments and no return value. Subclasses are used for functions with different numbers of arguments and return values. <a class="el" href="classArFunctor1.html" title="Base class for functors with 1 parameter. ">ArFunctor1</a>, <a class="el" href="classArFunctor2.html" title="Base class for functors with 2 parameters. ">ArFunctor2</a>, <a class="el" href="classArRetFunctor.html" title="Base class for functors with a return value. ">ArRetFunctor</a>, <a class="el" href="classArRetFunctor1.html" title="Base class for functors with a return value with 1 parameter. ">ArRetFunctor1</a>, and <a class="el" href="classArRetFunctor2.html" title="Base class for functors with a return value with 2 parameters. ">ArRetFunctor2</a> for example. When invoked, the arguments may be supplied which are passed to the target function or method, and a return value may also be given. The types for the arguments and/or return value are given as template arguments.</p>
<p>When creating a functor object, however, you must also provide the type and instance of an object to invoke the method of; or explicitly state that the function is a class-less global function. Do this by using one of the concrete base classes of <a class="el" href="classArFunctor.html" title="An object which allows storing a generalized reference to a method with an object instance to call la...">ArFunctor</a> instead of the abstract classes: <a class="el" href="classArFunctorC.html" title="Functor for a member function. ">ArFunctorC</a>, <a class="el" href="classArFunctor1C.html" title="Functor for a member function with 1 parameter. ">ArFunctor1C</a>, <a class="el" href="classArFunctor2C.html" title="Functor for a member function with 2 parameters. ">ArFunctor2C</a>, <a class="el" href="classArRetFunctorC.html" title="Functor for a member function with return value. ">ArRetFunctorC</a>, <a class="el" href="classArRetFunctor1C.html" title="Functor for a member function with return value and 1 parameter. ">ArRetFunctor1C</a>, <a class="el" href="classArRetFunctor2C.html" title="Functor for a member function with return value and 2 parameters. ">ArRetFunctor2C</a>, <a class="el" href="classArGlobalFunctor.html" title="Functor for a global function with no parameters. ">ArGlobalFunctor</a>, <a class="el" href="classArGlobalFunctor1.html" title="Functor for a global function with 1 parameter. ">ArGlobalFunctor1</a>, etc.</p>
<p>Example:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>ExampleClass {</div><div class="line"><span class="keyword">public</span>:</div><div class="line">    <span class="keywordtype">void</span> aFunction(<span class="keywordtype">int</span> n);</div><div class="line">};</div><div class="line"></div><div class="line">...</div><div class="line">  </div><div class="line">ExampleClass obj;</div><div class="line"><a class="code" href="classArFunctor1C.html">ArFunctor1C&lt;ExampleClass, int&gt;</a> functor(&amp;obj, &amp;ExampleClass::aFunction);</div><div class="line"></div><div class="line">...</div><div class="line"></div><div class="line">functor.invoke(42);</div></div><!-- fragment --><p><code>ExampleClass</code> is a class which contains a function called <code>aFunction()</code>. The functor <code>functor</code> is declared as an <code><a class="el" href="classArFunctor1C.html" title="Functor for a member function with 1 parameter. ">ArFunctor1C</a></code>, a functor which invokes a class method and takes one argument. The template parameters specify the type of the class (<code>ExampleClass</code>) and the type of the method argument (<code>int</code>). <code>functor</code> is then initialized with a pointer to the <code>ExampleClass</code> instance to call the method on, and a pointer to the class method to call. When a functor is contained within the class, it is typcially initialized in the constructor, giving <code>this</code> as the object instance.</p>
<p>A functor must be initialized with the method to call and, if a "C" functor, a class instance. An unitilialized functor will crash at runtime when invoked.</p>
<p>It is also possible to give values for the method arguments in the functor initialization, see <a class="el" href="classArFunctor.html" title="An object which allows storing a generalized reference to a method with an object instance to call la...">ArFunctor</a> documentation for details.</p>
<p>Once the functor object is created in this fashion, it can now be passed to another function or object that wants a callback functor. And the method <code>ExampleClass::aFunction()</code> will be called on the object <code>obj</code> when the functor is invoked.</p>
<p>To invoke a functor, simply call the invoke() function on the functor. If it takes arguments, call invoke() with those arguments. If the functor has a return value, call invokeR. The return value of the function will be passed back through the invokeR() function. If the functor was initialized with argument values, and invoke() is called without argument values, the argument values provided at initialization are passed.</p>
<h1><a class="anchor" id="userInput"></a>
Keyboard and Joystick Input</h1>
<p>ARIA provides several classes getting live joystick and keyboard input, and action classes (see <a class="el" href="index.html#actions">Actions</a>) that use that input to drive the robot.</p>
<p><a class="el" href="classArJoyHandler.html" title="Interfaces to a computer joystick. ">ArJoyHandler</a> is a cross-platform interface to joystick data. It's key functions are ArJoyHandler::getButtons, <a class="el" href="classArJoyHandler.html#acf7e26a06019c33105bdd56bdc495694" title="Gets the adjusted reading, as integers, based on the setSpeed. ">ArJoyHandler::getAdjusted</a>, <a class="el" href="classArJoyHandler.html#a6a940625d5e5257e280929b0ed3e84c4" title="Sets the maximums for the x, y and optionally, z axes. ">ArJoyHandler::setSpeeds</a>, and <a class="el" href="classArJoyHandler.html#ada6b0192aa636e9adc1bdf9b8ed2943d" title="Gets the adjusted reading, as floats, between -1.0 and 1.0. ">ArJoyHandler::getDoubles</a>.</p>
<p><a class="el" href="classArKeyHandler.html" title="Perform actions when keyboard keys are pressed. ">ArKeyHandler</a> is a cross-platform interface for recieving single keystroke events (instead of buffered lines of text). It's key function is <a class="el" href="classArKeyHandler.html#ad5442ebb21cd242ab168e94686e06759" title="This adds a keyhandler, when the keyToHandle is hit, functor will fire. ">ArKeyHandler::addKeyHandler</a>, which binds a specific key to a given functor. It contains an enum <a class="el" href="classArKeyHandler.html#a665246cd772590dd02ea299dd047899c" title="These are symbols for the non-ascii keys. ">ArKeyHandler::KEY</a> that contains values for special keys. You can also attach a key handler to a robot with <a class="el" href="classArRobot.html#ab4ea516667d2358f35b435d97b616ab1" title="Attachs a key handler. ">ArRobot::attachKeyHandler()</a>, which adds some default key handlers, including a handler for Escape that disconnects and exits the program (especially useful on Windows, where Ctrl-C or the terminal close box won't properly clean up). Since a PC can only have ony keyboard, ARIA keeps an <a class="el" href="classArKeyHandler.html" title="Perform actions when keyboard keys are pressed. ">ArKeyHandler</a> pointer globally, which may be queried with <a class="el" href="classAria.html#a5b8042b38b19d6a5d3cfbed4df483e67" title="Gets a pointer to the global key handler, if one has been set with setKeyHandler() ...">Aria::getKeyHandler()</a>.</p>
<dl class="section note"><dt>Note</dt><dd>if you are using Linux, creating a key handler will make the program hang if put into the background with Ctrl-Z.</dd></dl>
<p>ARIA provides two simple actions, <a class="el" href="classArActionKeydrive.html" title="This action will use the keyboard arrow keys for input to drive the robot. ">ArActionKeydrive</a> and <a class="el" href="classArActionJoydrive.html" title="This action will use the joystick for input to drive the robot. ">ArActionJoydrive</a>, to drive a robot from keyboard and joystick input. These actions are used by the <a class="el" href="teleopActionsExample_8cpp-example.html">teleopActionsExample.cpp</a> example program. ARIA also provides a more flexible <a class="el" href="classArActionRatioInput.html" title="Action that requests motion based on abstract ratios provided by diferent input sources. ">ArActionRatioInput</a>, which can combine several input sources (such as keyboard, computer joystick, robot-platform (microcontroller) joystick, or teleoperation commands recieved via ArNetworking) in a more consistent and configurable manner. See the class documentation for more details.</p>
<h1><a class="anchor" id="threading"></a>
Threading</h1>
<p>ARIA is highly multi-threaded. This section presents some of the critical concepts behind writing threaded ARIA code.</p>
<p>ARIA provides a number of support classes to make it easier to write object-oriented threaded code. They are: <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a>, <a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a>, <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a>, and <a class="el" href="classArThread.html" title="POSIX/WIN32 thread wrapper class. ">ArThread</a>.</p>
<p>Thread-safe code mostly means proper coordination between threads when handling the same data. You want to avoid the problem of one or more threads reading or writing the data at the same time that other threads read or write the data. data. To prevent this problem from happening, the data needs to be protected with synchronization objects.</p>
<h2><a class="anchor" id="syncObject"></a>
Thread Syncronizing Objects</h2>
<p>In ARIA, the synchronization objects are <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a> and <a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a>. <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a> is the most useful one. <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a> (<em>mutex</em> is short for <em>mut</em>ual <em>ex</em>clusion.) provides a wrapper around system calls (pthreads functions on Linux and CriticalSection functions on Windows) that exclude other threads from continuing while the mutex object is "locked". When threads lock a mutex while accessing shared data, it is ensured that only one thread is accessing that shared data at a time. Therefore, the proper way to use a mutex is to lock it right before accessing the shared data, and to always unlock it when done. If the mutex is not already locked, then it becomes locked and the thread continues. If the mutex is already locked by another thread, then it blocks in the lock call until the other thread unlocks it. If a mutex is never unlocked (e.g. a function returns due to an error condition without unlocking it), then any further attempts to lock it will block forever, creating a "deadlock". See the mutex example program to see how <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a> is used. The documentation of a method may indicate whether locking is necessary before using it; in general, when using an object that may be shared by other threads, all threads using it must lock the same mutex (usually contained within the object's class with methods provided for locking and unlocking) while using the object.</p>
<p><a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a> is an occasionally used utility that puts the current thread to sleep until another thread signals it to wake up and continue executing. This can be used to wait in a thread for an indefinite amount of time until some event occurs in a another thread which signals the <a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a>.</p>
<h2><a class="anchor" id="asynctasks"></a>
Asynchronous Task Class</h2>
<p>ARIA provides the <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a> which can be subclassed to implement a long-running thread and its state as an object. As opposed to robot-syncronized tasks, asynchronous tasks run in seperate threads. Like <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a>, this class wraps the operating system's threading calls in a cross-platform way. Typically, an <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a> will reperesent a thread that runs in a loop for the entire program.</p>
<p>To use <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a>, derive a class from <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a> and override the <a class="el" href="classArASyncTask.html#a370bd38ad2a285af30cf722a9e3f4532" title="The main run loop. ">ArASyncTask::runThread()</a> function. This function is automatically called within the new thread when that new thread gets created. To create and start the thread, call <a class="el" href="classArASyncTask.html#a1219f8fc48adfc07ab59ea414585c479" title="Create the task and start it going. ">ArASyncTask::create()</a>. When the <a class="el" href="classArASyncTask.html#a370bd38ad2a285af30cf722a9e3f4532" title="The main run loop. ">ArASyncTask::runThread()</a> function exits, the thread will exit and be destroyed. Seperate threads can request that the task exit by calling <a class="el" href="classArASyncTask.html#adb6a00c292ff5aa6e8db8cd9d33747ac" title="Stop the thread. ">ArASyncTask::stopRunning()</a>, and within the thread, you can check for this request with <a class="el" href="classArThread.html#a05333f5f05022f42ab46a6dd8a8f1958" title="Get the running status of the thread, locking around the variable. ">ArASyncTask::getRunningWithLock()</a>.</p>
<p>This class is mainly a convenience wrapper around <a class="el" href="classArThread.html" title="POSIX/WIN32 thread wrapper class. ">ArThread</a> so that you can easily create your own object that encapsulates the concept of a thread.</p>
<h1><a class="anchor" id="aria"></a>
Global Data</h1>
<p>The static <a class="el" href="classAria.html" title="Contains global initialization, deinitialization and other global functions. ">Aria</a> class contains miscellaneous global data in ARIA.</p>
<p>ARIA contains a list of all the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> instances. Use the <a class="el" href="classAria.html#a1a3b572771bb33029637750f79eb31c6" title="Finds a robot in the global list of robots, by name. ">Aria::findRobot()</a> to find a robot by name, or use <a class="el" href="classAria.html#ab79a01958af8db8d1c38d62968c96dfa" title="Get a copy of the global robot list. ">Aria::getRobotList()</a> to get a list of the robots.</p>
<p>Use <a class="el" href="classAria.html#a9cbf9a172cb85275b05d391685f223e0" title="Gets the directory that ARIA resides in. ">Aria::getDirectory()</a> to find ARIA's top-level path (Usually either <code>C:\Program Files\MobileRobots\Aria</code> on Windows, or <code>/usr/local/Aria</code> on Linux). This is useful, for instance, to locate robot parameter files for individual operational details. Use <a class="el" href="classAria.html#a8196734fc2b1f74d9394a63763cc73c1" title="Sets the directory that ARIA resides in, to override default. ">Aria::setDirectory()</a> to change this path for the run of the program if you feel the need to override what ARIA has decided.</p>
<p>Call <a class="el" href="classAria.html#ad99c16b5d947229d9f8e1c5b2d4cdd73" title="Initialize Aria global data struture and perform OS-specific initialization, including adding OS sign...">Aria::init()</a> at program start to perform global initialization, and use <a class="el" href="classAria.html#a6abc3d39b3e9548063bb8e78375acc17" title="Shutdown all Aria processes/threads, call exit callbacks, and exit the program. ">Aria::exit()</a> to exit all ARIA threads before exiting your program.</p>
<p>The <a class="el" href="classAria.html" title="Contains global initialization, deinitialization and other global functions. ">Aria</a> class also contains global objects for sharing configuration parameters and other information: see <a class="el" href="index.html#arconfig">ArConfig</a> and <a class="el" href="index.html#arinfogroup">Shared Info Groups</a> sections below.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="index.html#arconfig">ArConfig</a> </dd>
<dd>
<a class="el" href="index.html#arinfogroup">Shared Info Groups</a></dd></dl>
<h1><a class="anchor" id="devices"></a>
Device and Accessory Interface Classes</h1>
<p>ARIA includes classes to communicate with various kinds of devices.</p>
<p>(Many of these devices are optional accessories, and not all robots have them installed.)</p>
<p>Some are mentioned below. See <a class="el" href="group__DeviceClasses.html">Device Interface Classes</a> for a list.</p>
<ul>
<li>
<p class="startli">Range devices. See <a class="el" href="index.html#rangeDevices">Range Devices</a> for more about range devices. </p><ul>
<li>
The various subclasses of <a class="el" href="classArLaser.html" title="ArRangeDevice interface specialized for laser rangefinder sensors; see ArRangeDevice for more data ac...">ArLaser</a> are for laser rangefinder sensors. Use <a class="el" href="classArLaserConnector.html" title="Create laser interface objects (for any kind of laser supported by ARIA) and connect to lasers based ...">ArLaserConnector</a> to automatically create and set up <a class="el" href="classArLaser.html" title="ArRangeDevice interface specialized for laser rangefinder sensors; see ArRangeDevice for more data ac...">ArLaser</a> objects of the appropriate types based on robot and program configuration parameters. The lasers created by <a class="el" href="classArLaserConnector.html" title="Create laser interface objects (for any kind of laser supported by ARIA) and connect to lasers based ...">ArLaserConnector</a> will be available as <a class="el" href="classArLaser.html" title="ArRangeDevice interface specialized for laser rangefinder sensors; see ArRangeDevice for more data ac...">ArLaser</a> objects stored in <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>. </li>
<li>
<a class="el" href="classArSonarDevice.html" title="Keep track of recent sonar readings from a robot as an ArRangeDevice. ">ArSonarDevice</a> for Pioneer and Amigobot built-in sonar. </li>
<li>
<a class="el" href="classArBumpers.html" title="A class that treats the robot&#39;s bumpers as a range device. ">ArBumpers</a> treats the robot's bumper switch triggers as positions for range device readings. </li>
<li>
ArRangeDeviceFilter provides an <a class="el" href="classArRangeDevice.html" title="The base class for all sensing devices which return range information from the device (mounted on a r...">ArRangeDevice</a> interface to data from any other range device that has been filtered in different ways. </li>
<li>
<a class="el" href="classArForbiddenRangeDevice.html" title="Class that takes forbidden lines and turns them into range readings. ">ArForbiddenRangeDevice</a> is a virtual range device that returns readings indicating the edges of forbidden lines and forbidden areas from an <a class="el" href="classArMap.html" title="A map of a two-dimensional space the robot can navigate within, and which can be updated via the Aria...">ArMap</a> </li>
<li>
<a class="el" href="classArIRs.html" title="A class that treats a robot&#39;s infrared sensors as a range device. ">ArIRs</a> treats triggers of a Peoplebot's infrared "table" sensors as positions for range device readings. </li>
</ul>
<p></p>
<p class="endli"></p>
</li>
<li>
<p class="startli">Pan/Tilt servos and camera bases. <a class="el" href="classArPTZ.html" title="Base class which handles the PTZ cameras. ">ArPTZ</a> defines a common interface, and subclasses access specific devices, including: </p><ul>
<li>
<a class="el" href="classArVCC4.html" title="Control the pan, tilt, and zoom mechanisms of the Canon VC-C4 and VC-C50i cameras. ">ArVCC4</a> provides pan, tilt, zoom and other control of a Canon camera via the robot microcontroller's AUX serial port. </li>
<li>
<a class="el" href="classArSonyPTZ.html" title="A class to use the sony pan tilt zoom unit. ">ArSonyPTZ</a> provides pan, tilt, zoom and other actions of a Sony camera via the robot microcontroller's AUX serial port. </li>
<li>
<a class="el" href="classArDPPTU.html" title="Driver for the DPPTU. ">ArDPPTU</a> provides control of a Directed Perceptions Pan/Tilt unit (used for stereo cameras). </li>
</ul>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArAnalogGyro.html" title="Use onboard gyro to improve the heading in an ArRobot object&#39;s pose value. ">ArAnalogGyro</a> provides data from the optional analog gyro on Pioneer, PeopleBot, PatrolBot, PowerBot or AmigoBot. If the HasGyro parameter in the robot's internal firmware configuration is 2 (the default on most robots), then the robot automatically uses the gyro for position correction before sending its pose estimate to ARIA. However, if GyroType is 1, then create an <a class="el" href="classArAnalogGyro.html" title="Use onboard gyro to improve the heading in an ArRobot object&#39;s pose value. ">ArAnalogGyro</a> object to begin receiving data from the robot and allow it to apply those corrections to the position in the <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> object.</p>
<p>The gyro also measures its own temperature as part of its operation, and <a class="el" href="classArAnalogGyro.html" title="Use onboard gyro to improve the heading in an ArRobot object&#39;s pose value. ">ArAnalogGyro</a> makes that value available as well. </p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArGripper.html" title="Provides an interface to the Pioneer gripper device. ">ArGripper</a> provides access to a Pioneer gripper.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArP2Arm.html" title="ArP2Arm is the interface to the AROS/P2OS-based Pioneer 2 Arm servers, by means of which the robot mi...">ArP2Arm</a> provides access to a Pioneer arm.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArTCM2.html" title="Interface to the PNI TCM 2, TCM 2.5, and TCM 2.6 3-axis compass (magnetometer) that can sense absolut...">ArTCM2</a> provides access to an on-board TCM2 compass, if present.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArACTS__1__2.html" title="Communicate with ACTS. ">ArACTS_1_2</a> communicates with the ACTS program to get object tracking information.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArVersalogicIO.html" title="Interface to integrated digital and analog I/O interfaces on Versalogic VSBC8 and EBX-12 Cobra comput...">ArVersalogicIO</a> provides access to the digital and analog I/O ports on Versalogic motherboards (Linux only). (Support depends on whether the robot has a Versalogic motherboard, and which board it has.) </p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classArSystemStatus.html" title="Utility to get statistics about the host operating system (CPU usage, wireless link data...">ArSystemStatus</a> provides data about the operating system (Linux only) such as CPU usage and wireless network signal strength. </p>
<p class="endli"></p>
</li>
<li>
<a class="el" href="classArGPS.html" title="GPS Device Interface. ">ArGPS</a> provides access to data received from a Global Positioning System device. Subclasses implement special actions required for specific devices, such as <a class="el" href="classArNovatelGPS.html" title="GPS subclass to support the NovAtel ProPak G2 and other NovAtel &quot;OEM4&quot; devices. ">ArNovatelGPS</a> for the NovAtel G2 and similar devices and <a class="el" href="classArTrimbleGPS.html" title="GPS subclass to support the Trimble AgGPS and other Trimble GPS devices. ">ArTrimbleGPS</a> for the Trimble GPS. Use <a class="el" href="classArGPSConnector.html" title="Factory for creating GPS interface object (for any kind of GPS supported by ARIA) based on robot para...">ArGPSConnector</a> to create the appropriate <a class="el" href="classArGPS.html" title="GPS Device Interface. ">ArGPS</a> device based on robot and program configuration parameters.  </li>
</ul>
<p>Some device interfaces are provided by additional libraries, as well. See those libraries for details.</p>
<h1><a class="anchor" id="utility"></a>
Utility Classes</h1>
<p>Some of the general-purpose utility classes included with are <a class="el" href="classArMath.html" title="Common math operations. ">ArMath</a>, <a class="el" href="classArUtil.html" title="Contains various utility functions, including cross-platform wrappers around common system functions...">ArUtil</a>, <a class="el" href="classArTime.html" title="A class for time readings and measuring durations. ">ArTime</a>, <a class="el" href="classArPose.html" title="Represents an x, y position with an orientation. ">ArPose</a>, <a class="el" href="classArLog.html" title="Logging utility class. ">ArLog</a>, <a class="el" href="classArSectors.html" title="A class for keeping track of if a complete revolution has been attained. ">ArSectors</a>, <a class="el" href="classArRingQueue.html" title="An expanding ring queue. ">ArRingQueue</a>, <a class="el" href="classArLineFinder.html" title="This class finds lines out of any range device with raw readings (lasers for instance) ...">ArLineFinder</a>, the GPS-related subclasses of <a class="el" href="classAr3DPoint.html" title="Base class for points in 3 dimensional cartesian space. ">Ar3DPoint</a>, <a class="el" href="classArMD5Calculator.html" title="Calculates the MD5 checksum when reading or writing a text file using ArFunctors. ...">ArMD5Calculator</a> (and the functions in md5.h), <a class="el" href="classArMutex.html" title="Cross-platform mutex wrapper class. ">ArMutex</a>, <a class="el" href="classArCondition.html" title="Threading condition wrapper class. ">ArCondition</a> and <a class="el" href="classArASyncTask.html" title="Asynchronous task (runs in its own thread) ">ArASyncTask</a>. See <a class="el" href="group__UtilityClasses.html">Utility Classes</a> for a list of utility classes.</p>
<h1><a class="anchor" id="arconfig"></a>
ArConfig</h1>
<p><a class="el" href="classArConfig.html" title="Stores configuration information which may be read to and from files or other sources. ">ArConfig</a> is a mechanism for storing configuration parameters for different independent modules in a text file. The global <a class="el" href="classAria.html" title="Contains global initialization, deinitialization and other global functions. ">Aria</a> class maintains a global <a class="el" href="classArConfig.html" title="Stores configuration information which may be read to and from files or other sources. ">ArConfig</a> pointer which any program module may access. Use <a class="el" href="classArConfig.html#ad3aa76dcf6fd83874dda8ccb577415e0" title="Command to add a parameter to the given section with given priority. ">ArConfig::addParam</a> to register a new parameter with <a class="el" href="classArConfig.html" title="Stores configuration information which may be read to and from files or other sources. ">ArConfig</a>, and use <a class="el" href="classArConfig.html#ab6632033992fd48cb2369350a749f0b8" title="Adds a callback to be invoked when the configuration is loaded or reloaded. ">ArConfig::addProcessFileCB</a> to register a callback functor called when the configuration changes (by loading the file with <a class="el" href="classArConfig.html#a3e14491304e22ded38de8ffcc203035a" title="Parse a config file. ">ArConfig::parseFile</a>, or other means such as an update from a remote client via ArNetworking).</p>
<h1><a class="anchor" id="arinfogroup"></a>
Shared Info Groups</h1>
<p>In a program composed of multiple independent modules, it is often necessary to exchange or combine data between them in a general and immediate way. To do this, ARIA provides the <a class="el" href="classArStringInfoGroup.html" title="This class takes callbacks from different classes that want this string information and then lets you...">ArStringInfoGroup</a> class, of which the global ARIA class contains an instance (in addition to an <a class="el" href="classArConfig.html" title="Stores configuration information which may be read to and from files or other sources. ">ArConfig</a> instance used specifically for configuration information which changes infrequently, by loading a file or by user input.) An example of <a class="el" href="classArStringInfoGroup.html" title="This class takes callbacks from different classes that want this string information and then lets you...">ArStringInfoGroup</a> is the ArServerInfoStrings class contained in the ArNetworking auxiliary library. At program initialization, a callback functor may be added to the global <a class="el" href="classArStringInfoGroup.html" title="This class takes callbacks from different classes that want this string information and then lets you...">ArStringInfoGroup</a> object which on invocation immediately passes a string key/value pair from the <a class="el" href="classArStringInfoGroup.html" title="This class takes callbacks from different classes that want this string information and then lets you...">ArStringInfoGroup</a> object over to an ArServerInfoStrings object, which provides access to this data over the network (e.g. to MobileEyes). Independent components of the program may then change the values in the InfoGroup object without needing any special knowledge of the recipients of the data (in this example is the ArServerInfoStrings class). Since MobileEyes displays this data in a small table next to other robot information like position in speed, this is a useful way to provide informative statistics about the robot and software's current operation. (On Linux, for example, you could use the <a class="el" href="classArSystemStatus.html" title="Utility to get statistics about the host operating system (CPU usage, wireless link data...">ArSystemStatus</a> class to publish information from the operating system, like CPU load).</p>
<h1><a class="anchor" id="maps"></a>
Maps</h1>
<p>In mobile robot applications, you will often need to store a map of the robot's environment to use in navigation, localization, etc. ARIA provides the <a class="el" href="classArMap.html" title="A map of a two-dimensional space the robot can navigate within, and which can be updated via the Aria...">ArMap</a> class for reading map data from a file, obtaining and modifying its contents in your application, and writing it back to file. An <a class="el" href="classArMap.html" title="A map of a two-dimensional space the robot can navigate within, and which can be updated via the Aria...">ArMap</a> contains data about the sensed/sensable environment (walls, obstacles, etc.), and human-provided objects such as goal points.</p>
<p>The <a class="el" href="MapFileFormat.html">Map File Format</a> page describes the map file format in detail.</p>
<p>ARNL, SONARNL and MobileSim all use <a class="el" href="classArMap.html" title="A map of a two-dimensional space the robot can navigate within, and which can be updated via the Aria...">ArMap</a> format map files.</p>
<h1><a class="anchor" id="sockets"></a>
Sockets</h1>
<p>The <a class="el" href="classArSocket.html" title="socket communication wrapper ">ArSocket</a> class is a wrapper around the socket network communication layer of your operating system. ARIA mostly uses <a class="el" href="classArSocket.html" title="socket communication wrapper ">ArSocket</a> to open a server port and to connect to another server port.</p>
<p>To connect to a port, simply construct a socket containing the hostname or IP address of the host, a port number, and the ARIA socket type (TCP or UDP). For example:</p>
<div class="fragment"><div class="line"><a class="code" href="classArSocket.html">ArSocket</a> sock(<span class="stringliteral">&quot;host.name.com&quot;</span>, 4040, ArSocket::TCP);</div></div><!-- fragment --><p>Or call the <a class="el" href="classArSocket.html#ae9d803dcf9ad0bb72b790d3098ca8dc5" title="Connect as a client to a server. ">ArSocket::connect()</a> function, such as:</p>
<div class="fragment"><div class="line"><a class="code" href="classArSocket.html">ArSocket</a> sock;</div><div class="line">sock.<a class="code" href="classArSocket.html#ae9d803dcf9ad0bb72b790d3098ca8dc5">connect</a>(<span class="stringliteral">&quot;host.name.com&quot;</span>, 4040, ArSocket::TCP);</div></div><!-- fragment --><p>To open a server on (for example) port 4040, simply construct a socket:</p>
<div class="fragment"><div class="line"><a class="code" href="classArSocket.html">ArSocket</a> sock(4040, <span class="keyword">true</span>, ArSocket::TCP);</div></div><!-- fragment --><p>Or call <code>open(4040, ArSocket::TCP)</code> on an <a class="el" href="classArSocket.html" title="socket communication wrapper ">ArSocket</a> object constructed with the default constructor.</p>
<h1><a class="anchor" id="ArNetworking"></a>
ArNetworking</h1>
<pre class="fragment">For a more advanced networking infrastructure, see &lt;a target="_top"
href="../ArNetworking/docs/index.html"&gt;the ArNetworking companion
library&lt;/a&gt;, 
distributed with ARIA.  ArNetworking provides an extensible system of
data requests and updates between client and server applications via TCP or
UDP, using the same base "packet" concept as robot communication.  
For example, use ArNetworking to connect multiple robots working together, 
off-board user interfaces to on-board control servers, or robot control programs to 
off-board data resources.
</pre><h1><a class="anchor" id="sound"></a>
Sound and Speech</h1>
<p>ARIA provides some basic sound support.</p>
<p>ARIA's <a class="el" href="classArSoundsQueue.html" title="This class manages a queue of items to play as WAV files or as text to speak using a speech synthesiz...">ArSoundsQueue</a> provides a method for handling sound output generated by various components of a large ARIA application in sequence and in loops. It is a sound playback manager, which uses a thread-safe queue of sound requests, and runs a background processing thread for it. This lets you play sounds or trigger speech in order rather than simultaneously.</p>
<p>ARIA's <a class="el" href="classArSoundPlayer.html" title="This class provides a cross-platform interface for playing short sound samples. ">ArSoundPlayer</a> provides a basic cross-platform sound-file playback capability. Sound files are in WAV (Windows RIFF) format. This class provides static methods that can be used by <a class="el" href="classArSoundsQueue.html" title="This class manages a queue of items to play as WAV files or as text to speak using a speech synthesiz...">ArSoundsQueue</a> for sound file playback.</p>
<p>Note: The ARIA-based speech libraries (ArSpeechSynth_Cepstral, ArSpeechSynth_Festival, ArSpeechRec_Sphinx) are no longer supported by MobileRobots. Several open-source and commercial speech synthesis libraries are available.</p>
<p>Note: The ArNetAudio library is no longer supported by MobileRobots.</p>
<h1><a class="anchor" id="emacs"></a>
Emacs</h1>
<p>Here is the configuration specification the developers at MobileRobots Inc. use in their .emacs files, in case you want to modify the code using emacs and not deal with differences in indentation and such.</p>
<pre>
    (setq c-default-style '((other . "user")))
    (c-set-offset 'substatement-open 0)
    (c-set-offset 'defun-block-intro 2)
    (c-set-offset 'statement-block-intro 2)
    (c-set-offset 'substatement 2)
    (c-set-offset 'topmost-intro -2)
    (c-set-offset 'arglist-intro '++)
    (c-set-offset 'statement-case-intro '*)
    (c-set-offset 'member-init-intro 2)
    (c-set-offset 'inline-open 0)
    (c-set-offset 'brace-list-intro 2)
    (c-set-offset 'statement-cont 0)
    (defvar c-mode-hook 'c++-mode)
</pre><h1><a class="anchor" id="noneverydayC"></a>
Non-everyday use of C++</h1>
<p>ARIA uses some features of C++ that some programmers may not be aware of yet, and includes some workarounds for platform differences.</p>
<h2><a class="anchor" id="stl"></a>
Standard Template Library</h2>
<p>ARIA makes heavy use of the C++ standard template library (STL). So you should understand the STL in order to get the best use from some of the more advanced parts of ARIA.</p>
<h2><a class="anchor" id="defaultArgs"></a>
Default Arguments</h2>
<p>In the function declaration a default value for an argument may be specified. Arguments with default values may then be omitted from the function call.</p>
<p>For example, after declaring this function with a default value for its integer argument: </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> foo(<span class="keywordtype">int</span> number = 3);</div></div><!-- fragment --><p> it can be used in two different ways: </p><div class="fragment"><div class="line"><span class="comment">// Use the default value for the argument:</span></div><div class="line">foo();</div><div class="line"></div><div class="line"><span class="comment">// Or, use don&#39;t use the default:</span></div><div class="line">foo(99);   </div></div><!-- fragment --><p>This behavior is quite useful for having defaults for more obscure options you will usually not need to change, but still allowing you to change them if necessary without making ARIA more complex.</p>
<p>Also note that the function definition must not have the assignment in it, only the declaration. Therefore the definition if our example function would look like this: </p><div class="fragment"><div class="line"><span class="keywordtype">void</span> foo(<span class="keywordtype">int</span> number)</div><div class="line">{ </div><div class="line">  <span class="comment">//...</span></div><div class="line">}</div></div><!-- fragment --><h2><a class="anchor" id="constructorChaining"></a>
Constructor Chaining</h2>
<p>Constructor chaining is quite simple though sometimes not used by C++ programmers. Each constructor can give arguments to the constructors of the member variables it contains and to the constructors of classes from which it inherits. For example if you have:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>BaseClass</div><div class="line">{</div><div class="line"><span class="keyword">public</span>:</div><div class="line">  BaseClass(<span class="keywordtype">int</span> someNumber);</div><div class="line">};</div></div><!-- fragment --><p> and </p><div class="fragment"><div class="line"><span class="keyword">class </span>SubClass : <span class="keyword">public</span> BaseClass</div><div class="line">{</div><div class="line"><span class="keyword">public</span>:</div><div class="line">  SubClass(<span class="keywordtype">void</span>);</div><div class="line">  <span class="keywordtype">int</span> anotherNumber;</div><div class="line">};</div></div><!-- fragment --><p> When you write your constructor for SubClass you can initialize both baseClass and anotherNumber: </p><div class="fragment"><div class="line">SubClass::SubClass(<span class="keywordtype">void</span>) : BaseClass(3), anotherNumber(37)</div><div class="line">{</div><div class="line">    <span class="comment">// ...</span></div><div class="line">}</div></div><!-- fragment --><p> Note how the constructors to be initialized must follow a colon (:) after the constructor, and be separated by commas. Member variables must be initialized in the order they are in the class. Note that initializing integers is not all that unique or useful, but using this to initialize callback <a class="el" href="index.html#functors">Functors</a> is quite useful.</p>
<p>Constructor chaining is used in many many places by ARIA, thus it must be understood in order to understand ARIA, but the above is all that really needs to be known.</p>
<h2><a class="anchor" id="charsAndStrings"></a>
Chars and Strings, Win workaround</h2>
<p>During development problems were encountered with Windows if a <code>std::string</code> was passed into a DLL. Thus for all input to ARIA <code>const char *</code> is used, but for all internal storage and all reporting <code>std::string</code>s are passed back out of ARIA.</p>
<h2><a class="anchor" id="arexport"></a>
AREXPORT</h2>
<p>Because of the Windows set up for using DLLs, this macro is used to take care of the required declaration attributes for DLLs. Largely users do not need to worry about <code>AREXPORT</code>, but only functions which have <code>AREXPORT</code> and inline functions are usable with DLLs in Windows (all of the ARIA functions which are documented in this manual are usable).</p>
<h2><a class="anchor" id="exceptions"></a>
Exceptions</h2>
<p>ARIA neither throws nor catches any exceptions.</p>
<h1><a class="anchor" id="Advanced"></a>
Topics and Esoterica</h1>
<h2><a class="anchor" id="pieceMealUse"></a>
Piecemeal Use of ARIA</h2>
<p>The most basic layer of ARIA is <a class="el" href="classArDeviceConnection.html" title="Base class for device connections. ">ArDeviceConnection</a> and subclasses, which handle low-level communication with the robot server. On top of the connection layer, we have a packet layer&ndash;<a class="el" href="classArBasePacket.html" title="Base packet class. ">ArBasePacket</a> and <a class="el" href="classArRobotPacket.html" title="Represents the packets sent to the robot as well as those received from it. ">ArRobotPacket</a>&ndash;the basic algorithms for constructing command packets and decoding server information packets.</p>
<p>Above the packet layer is the packet handler classes, <a class="el" href="classArRobotPacketReceiver.html" title="Given a device connection it receives packets from the robot through it. ">ArRobotPacketReceiver</a> and <a class="el" href="classArRobotPacketSender.html" title="Given a device connection this sends commands through it to the robot. ">ArRobotPacketSender</a>, when send and receive packets to and from the robot. Finally, on top of all these lowest layers is <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a>, which is a gathering point for all things, but can be used in a quite basic format without all of the bells and whistles. <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> has built-in tasks, actions, state reflection and so forth, all of which can be disabled from the constructor (<a class="el" href="classArRobot.html#ab92dd002af5898b61ca6213e0c59f54e" title="Constructor. ">ArRobot::ArRobot</a>) and ignored or reimplemented.</p>
<p>Also note that if all you do is turn off state reflection, which only affects sending ArRobot-mediated motion commands to the robot, not receiving SIPs from the robot, none of the other activities which <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> engages on its loop will take up hardly any time, so it probably isn't worth building your own set of tasks, but the power to do so is there for the intrepid.</p>
<p>One other thing worth noting is that you can call <a class="el" href="classArRobot.html#ac59821b09bfe11ed80d30415c4788568" title="This function loops once... only serious developers should use it. ">ArRobot::loopOnce()</a> and it will run through its loop a single time and return. This is so that you can use ARIA from your own loop or control structure. You must call loopOnce() regularly and at least every 100ms to maintain consistent communication with the robot.</p>
<h2><a class="anchor" id="hardConnectRobot"></a>
Connecting with a Robot or the Simulator the hard way</h2>
<p><a class="el" href="classArDeviceConnection.html" title="Base class for device connections. ">ArDeviceConnection</a> is ARIA's communications object; <a class="el" href="classArSerialConnection.html" title="Utility for connecting to and communicating with devices through a serial port. ">ArSerialConnection</a> and <a class="el" href="classArTcpConnection.html" title="For connecting to a device through a TCP network socket. ">ArTcpConnection</a> are its built-in children most commonly used to manage communication between a MobileRobots or ActivMedia robot or the robot simulator, respectively. These classes are not device-specific, however, so use <a class="el" href="classArSerialConnection.html" title="Utility for connecting to and communicating with devices through a serial port. ">ArSerialConnection</a>, for instance, to also configure a serial port and establish a connection with a robot accessory, such as with the SICK laser range finder.</p>
<h2><a class="anchor" id="openDevice"></a>
Opening the Connection</h2>
<p>After creating and opening a device connection, associate it with its ARIA device handlers, most commonly with <a class="el" href="classArRobot.html#afdefce1c9f642dae8e68201ec509b898" title="Sets the connection this instance uses. ">ArRobot::setDeviceConnection</a> for the robot or the simulator.</p>
<p>For example, early in an ARIA program, specify the connection device and associate it with the robot:</p>
<div class="fragment"><div class="line"><a class="code" href="classArTcpConnection.html">ArTcpConnection</a> con;</div><div class="line"><a class="code" href="classArRobot.html">ArRobot</a> robot;</div></div><!-- fragment --><p>Later in the program, after initializing the ARIA system (<a class="el" href="classAria.html#ad99c16b5d947229d9f8e1c5b2d4cdd73" title="Initialize Aria global data struture and perform OS-specific initialization, including adding OS sign...">Aria::init()</a>; is mandatory), set the Connection port to its default values (for TCP, host is "localhost" and port number is 8101), and then open the port:</p>
<div class="fragment"><div class="line">con.setPort();</div><div class="line"><span class="keywordflow">if</span> (!con.openSimple())</div><div class="line"> {</div><div class="line">   printf(<span class="stringliteral">&quot;Open failed.&quot;</span>);</div><div class="line">   <a class="code" href="classAria.html#a184602a2b3799d61569ec55dd9508450">Aria::shutdown</a>();</div><div class="line">   <span class="keywordflow">return</span> 1;</div><div class="line"> }</div></div><!-- fragment --><p>TCP and Serial connections have their own implementation of open which is not inherited, but has default arguments that make the generic open work for the all default cases. And open returns a status integer which can be passed to the re-implemented and inherited <a class="el" href="classArDeviceConnection.html#a1468143d5b41948b64d80cebce07c6f3" title="Gets the string of the message associated with opening the device. ">ArDeviceConnection::getOpenMessage</a> in order to retrieve related status string, which is useful in reporting errors to the user without having to know about the underlying device.</p>
<h2><a class="anchor" id="devConnect"></a>
Robot Client-Server Connection</h2>
<p>After associating the device with the robot, now connect with the robot's servers, <a class="el" href="classArRobot.html#abc322326500b02e3e6e0bcaf7bf88d5f" title="Connects to a robot, not returning until connection made or failed. ">ArRobot::blockingConnect</a> or <a class="el" href="classArRobot.html#a48ba92e73c12765d68abd5289b3b1c84" title="Connects to a robot, from the robots own thread. ">ArRobot::asyncConnect</a>, for example, to establish the client-server connection between ARIA <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> and the robot microcontroller or robot simulator. The blockingConnect method doesn't return from the call until a connection succeeds or fails:</p>
<div class="fragment"><div class="line">robot.<a class="code" href="classArRobot.html#afdefce1c9f642dae8e68201ec509b898">setDeviceConnection</a>(&amp;con);</div><div class="line"><span class="keywordflow">if</span> (!robot.<a class="code" href="classArRobot.html#abc322326500b02e3e6e0bcaf7bf88d5f">blockingConnect</a>())</div><div class="line">{</div><div class="line">  printf(<span class="stringliteral">&quot;Could not connect to robot... Exiting.&quot;</span>);</div><div class="line">  <a class="code" href="classAria.html#a184602a2b3799d61569ec55dd9508450">Aria::shutdown</a>();</div><div class="line">  <span class="keywordflow">return</span> 1;</div><div class="line">}</div></div><!-- fragment --><p>The previous examples connect with the simulator through a TCP socket on your PC. Use <code>tcpConn.setPort(host, port)</code> to set the TCP hostname or IP address and related socket number to another machine on the network. For instance, use <code>tcpConn.setPort("bill", 8101);</code> to connect to the simulator which is running on the networked computer "bill" through port 8101.</p>
<p>Replace <code><a class="el" href="classArTcpConnection.html" title="For connecting to a device through a TCP network socket. ">ArTcpConnection</a> con;</code> with <code><a class="el" href="classArSerialConnection.html" title="Utility for connecting to and communicating with devices through a serial port. ">ArSerialConnection</a> con;</code> to connect with a robot through the default serial port (<code>/dev/ttyS0</code> or <code>COM1</code>), or another you specify with <a class="el" href="classArSerialConnection.html#a70d24c612f12fabc7c6fd9aff2de320d" title="Sets the port this connection will use. ">ArSerialConnection::setPort()</a>, such as <code>con.setPort("COM3");</code>.</p>
<p>At some point, you may want to open the port with the more verbose <code>con.open()</code>.</p>
<h2><a class="anchor" id="connrw"></a>
Connection Read, Write, Close and Timestamping</h2>
<p>The two main functions of a device connection are <a class="el" href="classArDeviceConnection.html#a0c7aa57e4734df6287c0393bdf7c186f" title="Reads data from connection. ">ArDeviceConnection::read</a> and <a class="el" href="classArDeviceConnection.html#ac9557146fcc027bef433c0d3807e82fa" title="Writes data to connection. ">ArDeviceConnection::write</a>. Simple enough. <a class="el" href="classArDeviceConnection.html#a9f701354a3cecec9e0b209a27e434f54" title="Closes the connection. ">ArDeviceConnection::close</a> also is inherited and important. You probably won't use direct read or write to the robot device, although you could. Rather, <a class="el" href="classArRobot.html" title="Central class for communicating with and operating the robot. ">ArRobot</a> provides a host of convenient methods that package your robot commands, and gather and distribute the various robot information packets, so that you don't have to attend those mundane details. See the next section for details.</p>
<p>All <a class="el" href="classArDeviceConnection.html" title="Base class for device connections. ">ArDeviceConnection</a> subclasses have support for timestamping (<a class="el" href="classArDeviceConnection.html#a92e9eb8baf15711a5984453f4e35451d" title="Gets the time data was read in. ">ArDeviceConnection::getTimeRead</a>). With the robot connection, timestamping merely says what time a robot SIP came in, which can be useful for interpolating the robot's location more precisely. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.11 </li>
  </ul>
</div>
</body>
</html>
